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.

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]