Item Data XML Import

Batch Mode

This function is driven from the Import/Export tab of the Administration menus, in the function named Item Data XML Import. When you access this function, you will see a screen similar to the following:

Batch interface to load an XML item file

Only a “merge” function is imported at this point in time. Future versions will support additional methods of importing item data. Use the Browse button to navigate to the XML file containing the item data to be imported. Then press the Upload XML file. Be prepared to wait until the XML data file is uploaded to the server. This may take some time, depending upon its size.

Note: To save time on a large import, you may zip the input file and upload the zipped file. ExtraView will automatically unzip the uploaded file.

Results screen from a batch XML import

While the file is being processed, you will see a status bar informing you of progress. Once complete, you will see a screen similar to the one above. If there are any errors in the import file, you will see these on the results screen.

API Commands

These commands are also explained in the ExtraView CLI & API Guide.

An API action named xml_insert creates a new record or records in the ExtraView database from input formatted as XML. The input can be made as part of the HTTP data stream, or can be input from a file in XML format.

Syntax:

http://www.myserver.com/evj/ExtraView/ev_api.action?
user_id=username
&password=password
&statevar=insert_xml
&xml_file_name=filename | &xml_string=xml_data
&template_file=file.html

  • Provide either the xml_file_name or xml_string, but not both. You provide xml_file_name if the input is from a file that exists at the time of the execution of the command. You provide xml_string, if the data for the insert is provided as part of the HTTP request. This string contains the XML data to be parsed.
  • template_file is the name of the template to be used for return value string generation. Generally, this template file is stored on the server in the WEB-INF/user_templates directory. On normal completion of the operation, this template undergoes parameter substitution with the following variable names:
     
    Tag Explanation
    __ID__ The item number of the last item inserted
    __NUMBER_ITEMS_INSERTED__ The number of inserted items
    __ITEM_TITLE__ The title of the ITEM_ID dictionary entry

    See the section on Templates in the ExtraView CLI & API Guide, for a full explanation of how to create user templates

    If no template file is requested, the command returns a completion message to the calling program via HTTP.

    On error completion, the return string contains an error message substituted into the error.html user template in the format:

    error-message “at line=xxx and column number=yyy”

    where xxx and yyy are the values returned by the XML parser.

    As an example, the following message may be returned:

    “The end-tag for element type "ITEM" must end with a '>' delimiter at line=8 and column number=9”
     

  • Only one record should be inserted with the XML_STRING in one call to the API. When the input is in a file, there is no restriction to the number of records in a single operation.

    Item Data Import Errors

    Error Message Explanation
    Ambiguous Area title: title The business area title in the XML is not unique within the database. Use its name instead.
    Ambiguous Module title: title The module with the title is not unique. Use the module name in this case to avoid conflicts
    Ambiguous Project title: title The project title in the XML is not unique within the database. Use its name instead.
    Ambiguous Repeating record title: title The repeating record with the title is not unique. Use the name in this case to avoid conflicts
    Ambiguous UDF title: title The UDF with the title is not unique. Use the UDF name in this case to avoid conflicts
    Bad zip file or invalid XML tag at beginning of file ExtraView cannot read the zip file with the XML data, or the XML tag at the beginning of the file is invalid
    Cannot dereference list entry for ddname [value] There is no list value corresponding to the value for the data dictionary name
    End Attachment tag outside Attachment The end attachment tags must be at the end of the attachment data
    End item tag outside item The end item tags must be at the end of the item data
    End module tag outside module The end module tags must be at the end of the module data
    End name tag outside name The end name tags must be at the end of the name data
    End Repeating record tag outside Repeating record The end repeating row tags must be at the end of the repeating row data
    End UDF tag outside UDF The end UDF tags must be at the end of the UDF data
    Illegal NAME construct ignored Provide valid name constructs
    Invalid characters in the title value: [value] The title value contains illegal characters
    No ddentry for dereferenced name: dd_name There is no data dictionary entry corresponding to dd_name
    No Area with title: title The business area with the title does not exist in the database
    No Module with title: title The module with the title does not exist
    No product name for module: name You must always provide the product_name field in the XML when adding modules
    No product name for release: name You must always provide the product_name field in the XML when adding repeating records which are dependent upon this field
    No Project with title: title The project with the title does not exist in the database
    No Repeating record with title: title The repeating record with the title does not exist
    No such XML file: file_name Indicates the input XML file does not exist
    No UDF with title: title The UDF with the title does not exist in the data dictionary
    Nothing to convert from XML to DB; quitting Input XML file appears to be empty
    Unrecognized end element tag: name The end tag for the name does not match the beginning tag for the name
    Unrecognized start element tag: tag_name The element tag name is not valid
    WARNING: this source locale: [locale] is not available in target system The DTD indicated that a locale is to be used that does not exist within the ExtraView installation
    Validation exception: exception General validation exception, as given in exception