Rules for importing from XML files

Prepare for importing by mapping. Much of the import work is the mapping. This ensures that the data from the source system matches the Optiva objects.

Confirm a one-to-one (1:1) direct mapping of most fields.
Map between single fields (for Optiva extension fields, parameters, context attributes, etc.)
Map data from multiple sources to one Optiva field.
Map data from one source to multiple Optiva fields.
Match field sizes between the source and Optiva to avoid loss of data.

Objects must be supported by the XML Export. Only the objects that can be exported in XML can be imported in XML.

When you import XML files, do not use group separators. For example, one thousand should be 1000 not 1,000.

Data must be the correct size.

Confirm the limitations of the field size in the Length_data column in the Validation form, for each tag. If the target field is smaller than the data, the import fails.

Follow the XML standards for specifying unicode or UTF-8.

Specify the encoding at the beginning of the import file according to XML standards. If you do not specify the encoding in the import files, they are assumed to be Unicode if they are double byte. If the format is not specified and are single byte, they are assumed to be ANSI or UTF-8.

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

Some related data must already be in the database.

<FSobjectINGR>: When Formulas and Specifications are imported with an <...INGR> detail tag, the item code must already exist in the FsItem table in the database.
<FSobjectTPALL> <FSSPECIFICATIONTP>: When Formulas, Items, and Projects (TPALL) or Specifications (TP) are imported with a parameter detail tag, the technical parameter must already exist in the FsTechParam table.
<FSobjectREF>: If references are imported, using the <...REF> detail tag, the referenced object must already exist in the database.
<FSDOC> or <FSobjectATTACH>: For document text, attachments, and URLs, ensure their function codes are assigned to the object type before you import them. This is performed through the Symbol form in Optiva. Function codes are stored in the FsDocCodes table in the database.
<FSEMBEDDEDOBJECTS>: When embedded files are imported, their function codes must be assigned before the object type is imported. This is performed through the Symbol form in Optiva. Embedded file codes are stored in the FsDocCodes table in the database.
<FSobjectST>: When Formulas and Items are imported with a set detail tag, the set member must exist in the FsSetMaster table.
<FSUSERGROUP> or <FSUSERROLE>: When a new user is imported with a group or role detail code, the group must exist in FsUserGroup and the role must exist in FsUserRole.
<FSobjectSTATUS>: When Formulas, Items, Specifications, Projects are imported with a status detail tag, values for the <STATUS_IND>, <APPROVAL_CODE>, and <HOLD_CODE> must exist in the FsStatus, FsApproval, and FsHold tables, respectively. To import status data, you must complete both of these tasks:
- Import <STATUS_IND> to the Status Detail table. Otherwise, the status does not change even if the import succeeds.
- Specify the <OBJECTSYMBOL> element in <FSxxxxSTATUS>. Otherwise, the import fails.

Add detail codes in the user interface in this order.

Sets, Security, Status, and Context.
Details on the form (for example, starting with Extension Tables, then References etc.).

The tags are case-insensitive.


Example	Is the same as …	Or
`<DESCRIPTION>`	`<description>`	`<Description>`

Values are case sensitive.

Values for tags are entered into the system with the exact uppercase and lowercase as they are entered in the import file. For example, the uppercase and lowercase in the value of the description tag are maintained:

<DESCRIPTION>Custom field for Customer Location</DESCRIPTION>

UPPERCASE and MAX LENGTH are edited by Optiva.

Edits to the values of some fields are applied by the system to convert them to all UPPERCASE. This is indicated by a column named "Edits Applied" in tables throughout this document. In this table, the value of the code is converted to all UPPERCASE characters and the max length is set to 20.


Name	Description	Value	Edits applied
ITEM_ CODE	Item code	Required	Converted to `UPPER CASE`. `Max length=20`

Default values apply to some fields.

Some classes have a row in the database for default field values. These values are used when no value is specified for a field. In this table, the default value for an item code is supplied. That value is used when no other value is specified in the import file.


Name	Description	Value	Edits applied
ITEM_ CODE	Manufactured item	Default as configured in the database, if a value is not supplied.	Converted to `UPPER CASE`

Use Optiva forms to enter data that cannot be imported.

If a value does not exist in the database, use the Optiva forms to create the data because Optiva sometimes adds associated data to related tables. Do not add data to the database directly.

Start with a small file.

During the debugging phase, start with an object that does not have much detail. Then add one detail code at a time to ensure that each successive part of the import is working correctly.

Use HTML numbers or the keypad for non-printable characters.

Special characters, including non-printable characters, can be represented for XML import using the keystroke or the HTML designation for the ASCII number. For example, attachment text can contain a carriage return between two lines:

This is the first line.

This is the second line.

To import a carriage return, use either of these methods.

The Enter key from the keypad.

<TEXT_DATA>This is the first line. 
This is the second line
</TEXT_DATA>

The HTML version of an ASCII number. The HTML number for a carriage return is .
```
<TEXT_DATA>This is the first line.&#13;
This is the second line
</TEXT_DATA>
```

Do not use the number pad to specify the ASCII number. For more information about ASCII characters, see www.asciitable.com.