Import of Item Data

There are three modes of importing item data from an XML format.

  • Batch Mode. In this mode, an XML formatted input file is processed sequentially, creating new issues in the ExtraView database. This is driven from an administration screen.
  • API Command. In this mode, an API command is executed, passing a single issue to ExtraView as part of the HTTP data stream. This issue is processed and with success is added to the database. The API command returns a success message or a failure error message.
  • API Command with Input File. In this mode, an API command is executed. The command references an input file with one or more issues to be imported to ExtraView. The file is processed and results are passed back to the calling command.

The XML data to be imported must adhere to the Document Type Definition (DTD) detailed below. This is supplied with ExtraView, in the
WEB-INF/data/xml_dtd directory of your installation, and can be directly referenced from your XML import file or data stream. The file name supplied is extraview_item.dtd.


<?xml version="1.0" encoding="UTF-8" ?>

<!ELEMENT locale (EMPTY) >
<!ATTLIST locale region CDATA "US">
<!ATTLIST locale language CDATA "en">
<!ATTLIST locale variant CDATA " ">

<!ELEMENT item_list (item*) >

<!ELEMENT item (short_descr , severity_level , priority , status , product_name , date_created ,
owner , timestamp , assigned_to , privacy , last_change_user , alt_id , area ,
project , category , resolution , product_line , date_last_status_change ,
date_closed , release_found , release_fixed , contact , originator ,
item_id, item_udf*, item_release*, item_module*, item_attachment* )>

<!ELEMENT item_udf (title_specifier?, name_specifier?, CDATA*)>

<!ELEMENT item_release (title_specifier?, name_specifier?,
short_descr , severity_level , priority , status , product_name , date_created ,
owner , timestamp , assigned_to , privacy , last_change_user , alt_id , area ,
project , category , resolution , product_line , date_last_status_change ,
date_closed , release_found , release_fixed , contact , originator ,
item_id, item_udf*)>

<!ELEMENT item_module (title_specifier?, name_specifier?, assigned_to ,status ,timestamp ,
rc_version ,last_change_user ,item_module_id )>

<!ELEMENT title_specifier (CDATA)>
<!ELEMENT name_specifier (#PCDATA)>

<!ELEMENT short_descr (CDATA) >
<!ELEMENT severity_level (CDATA) >
<!ELEMENT priority (CDATA) >
<!ELEMENT status (CDATA) >
<!ELEMENT product_name (CDATA) >
<!ELEMENT date_created (CDATA) >
<!ELEMENT owner (CDATA) >
<!ELEMENT timestamp (CDATA) >
<!ELEMENT assigned_to (CDATA) >
<!ELEMENT privacy (CDATA) >
<!ELEMENT last_change_user (CDATA) >
<!ELEMENT alt_id (CDATA) >
<!ELEMENT area (CDATA) >
<!ELEMENT project (CDATA) >
<!ELEMENT category (CDATA) >
<!ELEMENT resolution (CDATA) >
<!ELEMENT product_line (CDATA) >
<!ELEMENT date_last_status_change (CDATA) >
<!ELEMENT date_closed (CDATA) >
<!ELEMENT release_found (CDATA) >
<!ELEMENT release_fixed (CDATA) >
<!ELEMENT contact (CDATA) >
<!ELEMENT originator (CDATA) >
<!ELEMENT item_id (CDATA) >
<!ELEMENT rc_version (CDATA) >
<!ELEMENT item_module_id (CDATA) >

<!ELEMENT item_attachment (CDATA)>
<!ATTLIST item_attachment file_desc CDATA #IMPLIED >
<!ATTLIST item_attachment file_name CDATA #IMPLIED >
<!ATTLIST item_attachment path CDATA #IMPLIED >
<!ATTLIST item_attachment content_type CDATA #IMPLIED >
<!ATTLIST item_attachment file_size CDATA #IMPLIED >
<!ATTLIST item_attachment date_created CDATA #IMPLIED >
<!ATTLIST item_attachment created_by_user CDATA #IMPLIED >

Note that all data related to items, including repeating records, UDF’s, and attachments are described with the DTD and can all be imported by ExtraView.

A portion of a sample XML file is shown below, with two issues to be imported. This references the above DTD. Note that the attachment within the example import file is shortened, for brevity.

The following points should be noted about the import of items:

  • The DOCTYPE refers to the DTD and the path should correspond to the path where it is stored on your server.
  • UDF’s can be referred to by NAME or by TITLE. We recommend that you use the NAME wherever possible, as the TITLE field may not be unique across your installation. Furthermore, the TITLE may vary with the locale specified in the DTD. You may create different DTD’s for each locale, and use the localized TITLE within the XML files being imported.
  • We recommend that all character data is embedded within CDATA tags.
  • Certain constructs are required in the XML, following the web interface rules. For example, a file-name-attribute should always appear in the item-attachment-attributes list.
  • UserCustom methods prAddPreInsert and prAddPostInsert are executed on each item insert.
  • Allowed values between fields are ignored when you import a record via this interface. If you mistakenly create an invalid parent – child relationship, this will be indicated when you try to update the record via the web interface.
  • The ITEM_ID is allocated to the new issue at the time the ExtraView code validates the issue being read from the XML input. If the record is rejected for any reason, the ITEM_ID is discarded, and an issue with this ID will never be created. The next record to be imported will be allocated the next number in the sequence.
  • If a field is read-only, on the add screen layout (as defined by the user role, business area and project of the issue), then this will be respected with the item import function. Further, if this field has a default value defined in the data dictionary, this value will be inserted.
  • Attachments must be encoded using the Base64 algorithm.
  • Values in other CDATA sections may be encoded in Base64 if desired or required. Whether or not the string is encoded is signaled by a sentinel (“%25S”) in the front of the CDATA string. Encoding is required if any of the following arise:
    1. The string value starts with the sentinel value (“%25S”), or
    2. The string value contains the CDATA end marker (“]]>”), or
    3. The string value contains any non-CDATA-permissible characters. CDATA-permissible characters are defined using the following production with Unicode character values as derived from the web page at http://www.w3.org/TR/REC-xml - NT-Char

      Char ::= #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] |
      [#x10000-#x10FFFF]

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE extraview_item SYSTEM "file:///C:/path_to_my_dtd/extraview_item.dtd">
<ITEM_LIST>
<ITEM>
<AREA><![CDATA[Bugs]]></AREA>
<PROJECT><![CDATA[&Bugs Data&]]></PROJECT>
<CATEGORY><![CDATA[Software]]> </CATEGORY>
<PRODUCT_NAME><![CDATA[ExtraView]]></PRODUCT_NAME>
<ITEM_UDF>
<TITLE_SPECIFIER><![CDATA[OS]]></TITLE_SPECIFIER>
</ITEM_UDF>
<ITEM_RELEASE>
<RELEASE_FOUND><![CDATA[1.2.3.4]]></RELEASE_FOUND>
</ITEM_RELEASE>
<ITEM_RELEASE>
<ITEM_UDF><TITLE_SPECIFIER><![CDATA[This is text in a field]]></TITLE_SPECIFIER>
<![CDATA[BILL.SMITH]]>
</ITEM_UDF>
</ITEM_RELEASE>
</ITEM>
<ITEM>
<CATEGORY> <![CDATA[Software]]> </CATEGORY>
<PRODUCT_NAME> <![CDATA[ExtraView]]> </PRODUCT_NAME>
<ITEM_UDF><NAME_SPECIFIER>OP_SYS</NAME_SPECIFIER>
<![CDATA[Solaris]]>
</ITEM_UDF>
<ITEM_RELEASE>
<RELEASE_FOUND>
<![CDATA[2.3.4.5]]>
</RELEASE_FOUND>
</ITEM_RELEASE>
<ITEM_RELEASE>
<ITEM_UDF>
<NAME_SPECIFIER>RELEASE_COMMITTED_RELEASE</NAME_SPECIFIER>
<![CDATA[5.2.2.1]]>
</ITEM_UDF>
<RELEASE_FOUND>
<![CDATA[2.5.6]]>
</RELEASE_FOUND>
</ITEM_RELEASE>
<ITEM_ATTACHMENT FILE_DESC='Current log file' FILE_NAME='EVJ.log' PATH='C:/t/' CONTENT_TYPE='text/plain' >
<ATA[VEhJUyBJUyBBIEZJTEU=]]>
</ITEM_ATTACHMENT>
</ITEM>
</ITEM_LIST>