# xml_import_reference

### General Description of XML Import Jobs

All XML import jobs follow the same schema and can be largely handled in a generic way.
They have the same input parameters (`Flags`, `Options`, `XML`) and basically the same return parameters.

Via `Flags` the general behavior of the job is controlled (e.g. error list generation or XML validation).
Via `Options` specific checks (e.g. key field check) can be enabled or disabled.
`XML` contains the data describing the object to be inserted.
`JobUserGUID` allows changing the user context for this job.

#### Import Schema

The `XML` argument must be passed Base64-encoded, as otherwise the server would have problems with special characters or UTF-16/UCS-4 formats.
A schema exists for the XML structure, which can be retrieved via [dms.GetXMLSchema](../dms.md#dms.GetXMLSchema) (parameter `Schema` = `"DMSData"`).

If attributes are set that the job should not evaluate, text attributes must be pre-defined with the empty string `""` and numeric attributes with `-1`.

**Example — XMLInsert for a document**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive internal_name="patient">
    <ObjectType internal_name="medical_letter" type="DOCUMENT">
      <Object>
        <Fields>
          <Field internal_name="firstname">Max</Field>
        </Fields>
      </Object>
    </ObjectType>
  </Archive>
</DMSData>
```

##### XML Elements

`DMSData`::
Root element.
Via the optional attribute `query_language` the language for DMS identifiers can be specified (e.g. `"7"` for German, `"9"` for English).
If the attribute is omitted or set to `"0"`, the server default language applies.

`Archive`::
Identifies the cabinet in which the object type is located or should be inserted.
If no attribute is specified, the server tries to determine the cabinet based on the object type — however, this affects performance.
Identification attributes: `internal_name` (internal cabinet name), `name` (cabinet name), `id` (object type ID), `osguid` (GUID).

`ObjectType`::
Defines the object type of the object to be processed.
The attribute `type` is mandatory and indicates whether it is a folder (`FOLDER`), register (`REGISTER`) or document (`DOCUMENT`).
Identification attributes: `internal_name`, `name`, `id`, `table`, `osguid`, or a valid combination of `maintype` and `cotype` (see Object Type ID).

`Object`::
Contains information about the concrete object to be processed.
For jobs that require an existing object (e.g. [dms.XMLUpdate](../dms.md#dms.XMLUpdate)), `object_id` must be specified as an attribute.
For location specification (e.g. with [dms.XMLInsert](../dms.md#dms.XMLInsert)) `register_id`, `register_type` and/or `folder_id` are used.
For documents `maintype` can be set.
Variants of W-documents are specified via `variantparent_id` (ID of the parent document).
Via `concurrency_timestamp` (combined with the field value `MODIFYTIME`) it can be checked whether the object has been changed by another user since the query.
`sourceparent_id` determines which location is affected when moving/deleting documents with multiple locations.

`Fields`::
May only appear once per object. Contains the list of fields to be processed.

`Field`::
Describes a single field.
Identification attributes: `internal_name`, `name`, `dbname`, `sortpos`, `osguid`.
The element text contains the value to be assigned.
System fields are marked with the attribute `system="1"`.
The following system fields can be set via `Field`:
+
| Database name \|Internal Name \|Meaning |  |  |
|---|---|---|
| `OSOWNER` | [`OBJECT_USERGUID`](dms_reference.md) | Owner of the object |
| `FOREIGNID` | [`OBJECT_FOREIGNID`](dms_reference.md) | Foreign ID of a reference |
| `SYSTEMID` | [`OBJECT_SYSTEMID`](dms_reference.md) | System ID of an object |
+
Via the optional attribute `field_function` a calculated value can be set:
+
| Attribute value \|Meaning |  |
|---|---|
| `NULL` | Field value is inserted as DB NULL (empty field) |
| `OBJECT_ID` | Field value corresponds to the internal ID of the object |
| `USER` | Field value corresponds to the name of the logged-in user |
`MultiFields`::
May only appear once per object. Contains the list of multiple fields to be processed (only allowed for documents).

`Multifield`::
Identifies a specific multiple field.
Identification attributes: `internal_name`, `name`, `dbname`, `osguid`.

`Page`::
Designates a specific page of the multiple field; the page number is in the attribute `id`.

`Value`::
Contains the value for the associated page (as element text).

`TableFields`::
May only appear once per object. Contains the list of table fields to be processed.

`TableField`::
Identifies a table field (Table Control).
Identification attributes: `internal_name`, `name`, `dbname`, `osguid`.

`Row` (within `TableField`)::
Describes a row of the table field (summary of all columns of a row).

`Field` (within `Row`)::
Value of a specific column; identification via `internal_name`, `name` or `dbname`.
+
Alternatively to the `Row`/`Field` writing style, rows can be described by `Columns`/`Rows`/`Value` elements:

`Columns`::
Defines the column order for the following value list.

`Column`::
Describes a column; identification via `internal_name`, `name` or `dbname`.

`Rows`::
List of `Row` elements.

`Row` (within `Rows`)::
A row; the order of values corresponds to the column order defined under `Columns`.

`Value` (within `Row`)::
Value of a column as element text.

`Remarks`::
List of notes (`RemarkText` or `RemarkObject`).

`RemarkText`::
Note text for the object (as element text).

`RemarkObject`::
Links the object via notes to another object.
Attributes: `object_id` (ID of the object), `object_type` (type of the object).

#### Parameter `Flags`

Via `Flags` the general behavior of the job is controlled.
The flags can be added (e.g. `1 + 16 = 17` for error list as file in UTF-16).

| Flag (decimal) \|Description |  |
|---|---|
| `1` | The error list is returned in file format. |
| `2` | The job does not return an error list. |
| `4` | No validation of XML data against the XSD file. |
| `8` | The supplied files are not deleted on the server. |
| `16` | The returned error list is encoded in UTF-16 (default: UTF-8). |

#### Parameter `Options`

Via `Options` specific checks can be enabled or disabled.
The value is a semicolon-separated list in the format `OPTION1=1;OPTION2=0;...`.
Disabling can lead to significant performance improvement.

| Option \|Description \|Default \|Usable in |  |  |  |
|---|---|---|---|
| [[dms-option-APPENDFILESTOFRONT]]`APPENDFILESTOFRONT` | Indicates whether files to be appended during update and variant creation are appended before (`1`) or after (`0`) existing ones. | `0` (inactive) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUpdate](../dms.md#dms.XMLUpdate) |
| [[dms-option-ARCHIVABLE]]`ARCHIVABLE` | Indicates whether the document gets the status "archivable" (`1`) or "non-archivable" (`0`). | [dms.XMLInsert](../dms.md#dms.XMLInsert): `0` (inactive); [dms.XMLUpdate](../dms.md#dms.XMLUpdate): no change | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUpdate](../dms.md#dms.XMLUpdate), [dms.XMLCopy](../dms.md#dms.XMLCopy), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-ARCHIVEIMMEDIATELY]]`ARCHIVEIMMEDIATELY` | Indicates whether the document is archived immediately (`1`) or not (`0`). If the document cannot be archived, no document without pages is created. | `0` (inactive) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-ARCHIVEIMMEDIATELYOBJDEF]]`ARCHIVEIMMEDIATELYOBJDEF` | Indicates whether the object definition is also archived for an immediately archived document (`ARCHIVEIMMEDIATELY`) (`1`) or not (`0`). | `0` (inactive) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-CHECKACCESS]]`CHECKACCESS` | User rights for the object are checked (`1`) or not checked (`0`). | `1` (active) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUpdate](../dms.md#dms.XMLUpdate), [dms.XMLMove](../dms.md#dms.XMLMove), [dms.XMLDelete](../dms.md#dms.XMLDelete), [dms.XMLCopy](../dms.md#dms.XMLCopy), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-CHECKCATALOGUE]]`CHECKCATALOGUE` | Checks whether all passed catalog entries exist in the original catalog (`1`) or not (`0`). | `1` (active) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUpdate](../dms.md#dms.XMLUpdate), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-CHECKEXISTENCE]]`CHECKEXISTENCE` | Checks whether the specified object exists at the specified location (`1`) or not (`0`). | `1` (active) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUpdate](../dms.md#dms.XMLUpdate), [dms.XMLMove](../dms.md#dms.XMLMove), [dms.XMLDelete](../dms.md#dms.XMLDelete), [dms.XMLCopy](../dms.md#dms.XMLCopy), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-CHECKKEYFIELDS]]`CHECKKEYFIELDS` | Checks whether key fields are unique (`1`) or not (`0`). | `1` (active) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUpdate](../dms.md#dms.XMLUpdate), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-CHECKOBLIGATION]]`CHECKOBLIGATION` | Checks whether all required fields are set (`1`) or not (`0`). | `1` (active) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUpdate](../dms.md#dms.XMLUpdate), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-CHECKPOSITION]]`CHECKPOSITION` | Checks whether specified (target) objects (e.g. folders) exist (`1`) or not (`0`). | `1` (active) | [dms.XMLMove](../dms.md#dms.XMLMove), [dms.XMLCopy](../dms.md#dms.XMLCopy) |
| [[dms-option-CHECKREADONLY]]`CHECKREADONLY` | Checks whether no fields have been modified for which no write rights exist (`1`) or not (`0`). | `1` (active) | [dms.XMLUpdate](../dms.md#dms.XMLUpdate) |
| [[dms-option-COPYCASCADING]]`COPYCASCADING` | Indicates whether objects should be copied cascading if they contain sub-objects (`1`) or not (`0`). | `0` (inactive) | [dms.XMLCopy](../dms.md#dms.XMLCopy) |
| [[dms-option-COPYINDEXONLY]]`COPYINDEXONLY` | Indicates whether only index data is copied (`1`) or not (`0`). | `0` (inactive) | [dms.XMLCopy](../dms.md#dms.XMLCopy) |
| [[dms-option-COPYCREATEHISTORY]]`COPYCREATEHISTORY` | Indicates whether information about copying is recorded in the history (`1`) or not (`0`). | `1` (active) | [dms.XMLCopy](../dms.md#dms.XMLCopy) |
| [[dms-option-DELETECASCADING]]`DELETECASCADING` | Indicates whether objects should be deleted cascading even if they contain sub-objects (`1`) or not (`0`). | `0` (inactive) | [dms.XMLDelete](../dms.md#dms.XMLDelete) |
| [[dms-option-DELETEVARIANTMODE]]`DELETEVARIANTMODE` | Indicates whether deleting an inactive variant leads to deleting the entire variant tree (`1`) or not (`0`). | `0` (inactive) | [dms.XMLDelete](../dms.md#dms.XMLDelete) |
| [[dms-option-FULLTEXTFILEATTACHED]]`FULLTEXTFILEATTACHED` | Indicates whether the last submitted file should contain full-text data for the document (`1`) or not (`0`). | `0` (inactive) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUpdate](../dms.md#dms.XMLUpdate), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-HARDDELETE]]`HARDDELETE` | Indicates whether the object should be permanently deleted (not to trash, `1`) or not (`0`). | `0` (inactive) | [dms.XMLDelete](../dms.md#dms.XMLDelete) |
| [[dms-option-INITFIELDS]]`INITFIELDS` | Indicates whether all unset fields should be filled with default values (`1`) or not (`0`). | `1` (active) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUpdate](../dms.md#dms.XMLUpdate), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-INUSERTRAY]]`INUSERTRAY` | Indicates whether the object should be inserted into the user tray (`1`) or not (`0`). | `0` (inactive) | [dms.XMLMove](../dms.md#dms.XMLMove), [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-INWFTRAY]]`INWFTRAY` | Indicates whether the object should be inserted into the workflow tray (`1`) or not (`0`). | `0` (inactive) | [dms.XMLMove](../dms.md#dms.XMLMove), [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-KEEPLINKWHENEXISTS]]`KEEPLINKWHENEXISTS` | Indicates whether an already existing link should not be treated as an error (`1`) or already (`0`). Only with [dms.XMLCopy](../dms.md#dms.XMLCopy) in combination with `LINKDOCUMENT`. | `0` (inactive) | [dms.XMLCopy](../dms.md#dms.XMLCopy), [dms.XMLMove](../dms.md#dms.XMLMove) |
| [[dms-option-LINKDOCUMENT]]`LINKDOCUMENT` | Indicates whether a document should only receive a new location (`1`) or not (`0`). | `0` (inactive) | [dms.XMLCopy](../dms.md#dms.XMLCopy) |
| [[dms-option-REPLACEFILES]]`REPLACEFILES` | Indicates whether already stored files should be replaced by the passed ones (`1`) or appended (`0`). | [dms.XMLInsert](../dms.md#dms.XMLInsert) (variants): `1` (active); [dms.XMLUpdate](../dms.md#dms.XMLUpdate): `0` (inactive) | [dms.XMLUpdate](../dms.md#dms.XMLUpdate), [dms.XMLInsert](../dms.md#dms.XMLInsert) |
| [[dms-option-REPLACEMULTIFIELDS]]`REPLACEMULTIFIELDS` | Indicates whether the passed multiple fields replace the originals (`1`) or are appended (`0`). | `0` (inactive) | [dms.XMLUpdate](../dms.md#dms.XMLUpdate) |
| [[dms-option-REPLACEREMARKS]]`REPLACEREMARKS` | Indicates whether the passed remarks replace the originals (`1`) or are appended (`0`). | `0` (inactive) | [dms.XMLUpdate](../dms.md#dms.XMLUpdate) |
| [[dms-option-REPLACETABLEFIELDS]]`REPLACETABLEFIELDS` | Indicates whether the passed table fields replace the originals (`1`) or are appended (`0`). | `0` (inactive) | [dms.XMLUpdate](../dms.md#dms.XMLUpdate) |
| [[dms-option-TRUNCATEVALUES]]`TRUNCATEVALUES` | Indicates whether passed strings should be truncated if they are longer than defined (`1`) or not (`0`). | `0` (inactive) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown), [dms.XMLUpdate](../dms.md#dms.XMLUpdate) |
| [[dms-option-TYPELESS]]`TYPELESS` | Indicates whether the object should be inserted into the tray as typeless (`1`) or not (`0`). | `0` (inactive) | [dms.XMLInsert](../dms.md#dms.XMLInsert) |
| [[dms-option-UPDATEALLFIELDS]]`UPDATEALLFIELDS` | Indicates whether unspecified fields should be set to empty (`1`) or not (`0`). | `0` (inactive) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown), [dms.XMLUpdate](../dms.md#dms.XMLUpdate) |
| [[dms-option-VARIANTSAMELEVEL]]`VARIANTSAMELEVEL` | Indicates whether the variant should be inserted at the same level (`1`) or as "sub-variant" (`0`). | `0` (inactive) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-VARIANTSETACTIVE]]`VARIANTSETACTIVE` | Indicates whether the new variant should be set as "active" in the same step (`1`) or not (`0`). | `0` (inactive) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-VARIANTTRANSFERRETENTION]]`VARIANTTRANSFERRETENTION` | Indicates whether the new variant should inherit the planned retention time of the original document (`1`) or not (`0`). | `0` (inactive) | [dms.XMLInsert](../dms.md#dms.XMLInsert), [dms.XMLUnknownToKnown](../dms.md#dms.XMLUnknownToKnown) |
| [[dms-option-WFTOUSERTRAY]]`WFTOUSERTRAY` | Indicates whether when moving a document it should be moved from the workflow tray to the user tray (`1`) or not (`0`). | `0` (inactive) | [dms.XMLMove](../dms.md#dms.XMLMove) |

#### Parameter `JobUserGUID`

Via `JobUserGUID` the user context of the XML job can be changed.
If the GUID of a user is specified here, all checks (e.g. access rights) as well as storage operations are performed with the specified user.

> **Note:** This option is only available when jobs are called from other jobs on the server side.
A client will always refuse to set this option.

#### Parameter `File_N`

Alternatively to file transfer via the TCP stream, file paths can be passed as parameters `File_0`, `File_1`, etc. (ascending).
The parameter is of type `STRING` and contains the complete file path (local or UNC notation).
This requires that the caller is on the same computer as the server and that the path is reachable by the server with the necessary rights.

> **Note:** Either only a file list or exclusively `File_N` parameters can be passed — mixing both variants is not permitted.

#### Return Values

Besides job-specific return values, every job returns a return number.
On success this is `0`. On error the number can be used for a rough classification;
for a detailed analysis the XML error list (parameter `DMSResult`) is required.

The complete list of error codes – grouped by meaning and with verified job assignments – is documented centrally under [Error Codes](../errorcodes.md).

#### Cross-Job Restrictions

##### Date and Time Formats

Date fields can be imported in the following formats (DD = two-digit day, MM = month, YY/YYYY = two-/four-digit year):

* `DDMMYY`
* `DDMMYYYY`
* `DD.MM.YYYY`

Time fields are imported in the format `HH:MM:SS`.
Timestamps are imported in the format `DD.MM.YYYY HH:MM:SS` (date and time separated by a space).

##### Special Field Types

* A **checkbox** can only contain the values `0` or `1`.
* An **option button** can be identified by the name of the first button (according to tab order) or the name of the group field. Allowed values start at `0`.
* Field types **patient type**, **page**, **gender** and **question** accept both the first letter and the fully spelled-out value.
* **Decimal values** can start with a plus or minus sign; decimal places can be separated by dot or comma.
* In **multi-line text fields** individual lines are separated by Carriage Return + Line Feed; in XML by the combination `&#13;&#10`.
* In a **multi-language catalog** the technical values (corresponding to the database values) must be stored.

##### Additional Field Values

All fields can be set to empty via `field_function="NULL"`.
Via `field_function="OBJECT_ID"` the field gets the internal ID of the object.

#### The XML Error List

In case of an error, an XML error list is returned by default in the return parameter `DMSResult`.
Optionally, this can also be returned as a return file (Flags = `1`).

> **Note:** The first errors listed in the list are the most informative.

**Example — XML Error List**

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DMSData>
  <Messages>
    <Message Sourcename="oxjobdms">The field &gt;Table - Column2&lt; has a catalog; however, the value &gt;7&lt; could not be found in the catalog</Message>
    <Message Sourcename="oxjobdms">SAX Error: Common exception</Message>
    <Message Sourcename="oxjobdms">An error occurred during XML import</Message>
  </Messages>
</DMSData>
```