# DMS Engine (Engine `dms`)

The DMS executor includes jobs for requesting and processing index data, DMS objects and
folders, taking the security system into account. Furthermore, there are jobs to manage the
security system at the object level.

## Object Management

* [dms.XMLInsert](dms.md#dms.XMLInsert)
* [dms.XMLUpdate](dms.md#dms.XMLUpdate)
* [dms.XMLDelete](dms.md#dms.XMLDelete)
* [dms.XMLMove](dms.md#dms.XMLMove)
* [dms.XMLMoveType](dms.md#dms.XMLMoveType)
* [dms.XMLCopy](dms.md#dms.XMLCopy)
* [dms.XMLImport](dms.md#dms.XMLImport)
* [dms.XMLUnknownToKnown](dms.md#dms.XMLUnknownToKnown)
* [dms.GetXMLJobOptions](dms.md#dms.GetXMLJobOptions)

## Document Lock

Jobs for exclusively locking and releasing document files to prevent multiple users from editing the same document simultaneously.

* [dms.CheckOutDocument](dms.md#dms.CheckOutDocument)
* [dms.CheckInDocument](dms.md#dms.CheckInDocument)
* [dms.UndoCheckOutDocument](dms.md#dms.UndoCheckOutDocument)
* [dms.GetCheckedOutDocuments](dms.md#dms.GetCheckedOutDocuments)

## System Configuration

Jobs for querying archive structure and object type definitions, plus conceptual references.

* Object Type ID — structure and computation of the numeric `objecttypeid` from `maintype` and `cotype`
* [dms.GetObjDef](dms.md#dms.GetObjDef)
* [dms.GetObjectTypeByID](dms.md#dms.GetObjectTypeByID)
* [dms.GetXMLSchema](dms.md#dms.GetXMLSchema)
* [dms.GetOsMimetypes](dms.md#dms.GetOsMimetypes)

## Object Queries

Jobs for searching DMS objects and reading object and index data.

* [dms.GetResultList](dms.md#dms.GetResultList)
* [dms.GetDeletedObjects](dms.md#dms.GetDeletedObjects)
* [dms.GetObjectsByDigest](dms.md#dms.GetObjectsByDigest)
* [dms.GetUserTrayObjects](dms.md#dms.GetUserTrayObjects)
* [dms.SelectDistinctFieldValues](dms.md#dms.SelectDistinctFieldValues)
* [dms.GetObjectDetails](dms.md#dms.GetObjectDetails)
* [dms.GetObjectHistory](dms.md#dms.GetObjectHistory)
* [dms.GetShadowData](dms.md#dms.GetShadowData)
* [dms.WriteShadowData](dms.md#dms.WriteShadowData)

## Stored Queries

Jobs for managing and executing stored search queries.

* [dms.ExecuteStoredQuery](dms.md#dms.ExecuteStoredQuery)
* [dms.AddStoredQuery](dms.md#dms.AddStoredQuery)
* [dms.GetStoredQuery](dms.md#dms.GetStoredQuery)
* [dms.UpdateStoredQuery](dms.md#dms.UpdateStoredQuery)
* [dms.RemoveStoredQuery](dms.md#dms.RemoveStoredQuery)
* [dms.ConvertQuery](dms.md#dms.ConvertQuery)

## Security System

* [dms.CheckPermission](dms.md#dms.CheckPermission)
* [dms.CheckPermissions](dms.md#dms.CheckPermissions)
* [dms.CopySD](dms.md#dms.CopySD)
* [dms.CreateSD](dms.md#dms.CreateSD)
* [dms.DeleteSD](dms.md#dms.DeleteSD)
* [dms.ReadSD](dms.md#dms.ReadSD)
* [dms.SetSD](dms.md#dms.SetSD)

## Portfolios

* [dms.AddPortfolio](dms.md#dms.AddPortfolio)
* [dms.DelPortfolio](dms.md#dms.DelPortfolio)
* [dms.ModPortfolio](dms.md#dms.ModPortfolio)
* [dms.RemoveFromPortfolio](dms.md#dms.RemoveFromPortfolio)
* [dms.RetrievePortfolios](dms.md#dms.RetrievePortfolios)

## User-Related Data

* [dms.DeleteUserData](dms.md#dms.DeleteUserData)
* [dms.GetUserData](dms.md#dms.GetUserData)
* [dms.GetUserDataAsString](dms.md#dms.GetUserDataAsString)
* [dms.GetUserDataNames](dms.md#dms.GetUserDataNames)
* [dms.IsUserData](dms.md#dms.IsUserData)
* [dms.SetUserData](dms.md#dms.SetUserData)

## Events

* [dms.GetOsEvents](dms.md#dms.GetOsEvents)
* [dms.CreateOsEvent](dms.md#dms.CreateOsEvent)
* [dms.UpdateOsEvent](dms.md#dms.UpdateOsEvent)
* [dms.DeleteOsEvent](dms.md#dms.DeleteOsEvent)

## PDF Annotations

* [dms.GetPDFAnnotations](dms.md#dms.GetPDFAnnotations)
* [dms.GetPDFAnnotationInfo](dms.md#dms.GetPDFAnnotationInfo)
* [dms.CreatePDFAnnotations](dms.md#dms.CreatePDFAnnotations)
* [dms.UpdatePDFAnnotations](dms.md#dms.UpdatePDFAnnotations)
* [dms.DeletePDFAnnotations](dms.md#dms.DeletePDFAnnotations)

## Configuration

* [dms.GetConfValues](dms.md#dms.GetConfValues)

## Collaboration

* [dms.CreateCollaborationDocuments](dms.md#dms.CreateCollaborationDocuments)
* [dms.DeleteCollaborationDocumentsEx](dms.md#dms.DeleteCollaborationDocumentsEx)
* [dms.GetAllCollaborationDocuments](dms.md#dms.GetAllCollaborationDocuments)

## Revisits and Subscriptions

* [dms.GetRevisits](dms.md#dms.GetRevisits)
* [dms.GetSubscriptions](dms.md#dms.GetSubscriptions)

## Further Functions

* [dms.GetForeignObjects](dms.md#dms.GetForeignObjects)
* [dms.GetWorkflowObjects](dms.md#dms.GetWorkflowObjects)
* [dms.RestoreIndexdataVersion](dms.md#dms.RestoreIndexdataVersion)
* [dms.SetUserDataAsString](dms.md#dms.SetUserDataAsString)

## Undocumented Endpoints

The following jobs are offered by the enaio® server in the `dms` engine but are not currently described in this documentation:

Relations::
`dms.AddRel`, `dms.AddRelText`, `dms.AddRelTextLang`, `dms.DelRel`, `dms.DelRelText`, `dms.ModRel`, `dms.ModRelText`, `dms.ModRelTextLang`, `dms.RetrieveRelations`, `dms.RetrieveRelTexts`

Collaboration and projects::
`dms.ClearCollaborationDocuments`, `dms.DeleteCollaborationDocuments`, `dms.GetIngoingCollaborationDocuments`, `dms.GetOutgoingCollaborationDocuments`, `dms.MarkColabProjects`, `dms.UpdateCollaborationDocuments`, `dms.UpdateCollaborationDocumentsEx`

Revisits (in the dms engine, complementary to the abn revisits)::
`dms.AddToRevisit`, `dms.RemoveRevisit`, `dms.SetRevisitFlag`

Subscriptions and notifications (in the dms engine, complementary to the abn engine)::
`dms.RemoveAboNotification`

Search and full text::
`dms.GetFulltextResult`, `dms.GetLinkedObjects`, `dms.GetSimilarMails`

Configuration::
`dms.GetConfValuesAsString`

Direct insert/update/move/delete jobs (legacy, predating the XML layer)::
`dms.DeleteObject`, `dms.InsertIntoArchive`, `dms.InsertIntoDocument`, `dms.InsertIntoRegister`, `dms.MoveObject`, `dms.UpdateDocFileList`, `dms.UpdateDocumentData`, `dms.UpdateRegisterData`

Archive requests::
`dms.StartArchiveRequest`, `dms.StartDocRequest`, `dms.StartRegRequest`, `dms.UpdateArchiveData`

Shadow and index data::
`dms.ConvertClauses`, `dms.OnRightsChanged`, `dms.RestoreEcmClauses`

Schema and permissions::
`dms.GetShortObjectTypeFieldsInfo`, `dms.GetUserTypePermissions`, `dms.GetXMLSystemFields`

Other::
`dms.ChangePassword`, `dms.SAPSetBarcodeFlags`, `dms.ShowAccessStorage`

<a id="dms.AddPortfolio"></a>

## dms.AddPortfolio

This job creates a new folder. Via the 'objtype' attribute, the object type can also be specified
to which this folder should be restricted.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `PortfolioXML` | BASE64 | Yes | Description of the folder in XML format |
| `Mode` | INT | Yes | 0 (Default)=Searches for existing folders based on recipient or subject. If one or more folders exist, these are used or the first folder. 1=Creates a new folder. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `PortfolioID` | INT | — | ID of the new folder (-1 = Job failed) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Building PortfolioXML (Description: see Portfolio XML Format)**

```xml
<Portfolios>
  <Portfolio>
</Portfolio>
</Portfolios>
```

<a id="dms.AddStoredQuery"></a>

## dms.AddStoredQuery

This job creates a new stored query. The query must be passed in DMS Query
format. The query is converted to the internal format for stored queries.
Since the stored query format only allows a subset of DMS Query
request possibilities, there are certain limitations. See [dms.ConvertQuery](dms.md#dms.ConvertQuery).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags must be 0 |
| `Name` | STRING | Yes | Name of the query |
| `Query` | BASE64 | Yes | Request in [DMSQuery](xsd/DMSQuery.md) XML format |
| `[TreeParent]` | INT | No | ID of the desktop folder where the query is located |
| `[Scope]` | STRING | No | Scope. Allowed values: 'Public' for public queries, 'Private' for user-specific queries. Default is 'private'. |
| `[IconID]` | INT | No | ID of an icon that is displayed in the client. Default=0 |
| `[DefAction]` | INT | No | Action to be performed when opening the stored query. +<br>`0` = Execute (Default), `1` = Edit, `2` = Count hits |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `QueryID` | INT | — | ID of the query |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.CheckInDocument"></a>

## dms.CheckInDocument

This job checks the specified document in. The document is transferred to the server and deleted at
the location (specified in the File List parameter).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | 1 = the submitted document can be checked in from another station, otherwise 0 |
| `[ArchiveType]` | INT | No | Type of the cabinet |
| `ObjectType` | INT | Yes | Type of the object |
| `ObjectID` | INT | Yes | ID of the document |

### Input Files

| Name | Description |
|---|---|
| `File List` | Path and name of the document to be checked in |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Info` | STRING | — | If the document was checked out by another user/station, the name will be returned |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

### See Also

[dms.CheckOutDocument](dms.md#dms.CheckOutDocument)

<a id="dms.CheckOutDocument"></a>

## dms.CheckOutDocument

This job checks out the specified document. The document is marked as checked out in the database. The document itself must then be retrieved from the server using the job [std.StoreInCache](std.md#std.StoreInCache).

> **Note:** If a document without a file (reference-only document) is checked out, error `-1041` is returned with the error text "The document cannot be checked out because it has no pages".

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | 1 = the document will be checked out as 'external', otherwise 0 |
| `ArchiveType` | INT | Yes | Type of the cabinet |
| `ObjectType` | INT | Yes | Type of the object |
| `ObjectID` | INT | Yes | ID of the document |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `[Info]` | STRING | Optional | If the document is already checked out, the name of the checker-out will be returned |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

* `-1038` — The document has already been checked out.
* `-1041` — The document cannot be checked out because it has no pages (reference-only document).

### See Also

[dms.CheckInDocument](dms.md#dms.CheckInDocument) +
[dms.UndoCheckOutDocument](dms.md#dms.UndoCheckOutDocument)

<a id="dms.CheckPermission"></a>

## dms.CheckPermission

With this job, access permissions for individual DMS objects can be checked independently of the
used security system. To check whether an object can be inserted at a specific location, the location must be set via the parameter 'FolderID' or the parameter
'RegisterID', the parameter 'ObjectID' set to 0, and the access type 'W' checked.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `Access` | STRING | Yes | Access type to be checked (e.g. 'RWXDU' checks all access types) +<br>R = read index data +<br>W = write index data +<br>X = open/execute object +<br>D = delete object +<br>U = write object |
| `ObjectType` | INT | Yes | Type of the object |
| `ObjectID` | INT | Yes | ID of the object |
| `[RegisterType]` | INT | No | Type of the parent register +<br>`0 = not in any register (directly on folder level)` +<br>-1 = register-independent |
| `[RegisterID]` | INT | No | ID of the parent register |
| `[FolderID]` | INT | No | ID of the folder |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Access` | STRING | — | Granted access types (format corresponds to input parameter 'Access') |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.CheckPermissions"></a>

## dms.CheckPermissions

With this job, access permissions for a list of DMS objects can be checked.
Since performance is very important for this job, no archive objects and inactive
variants are considered.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `Access` | STRING | Yes | Access type to be checked (e.g. 'RWXDU' checks all access types) +<br>R = read index data +<br>W = write index data +<br>X = open/execute object +<br>D = delete object +<br>U = write object |
| `ObjectType<n>` | INT | Yes | Type of the objects. <n> is a sequential number starting with 1. |
| `ObjectList<n>` | String | Yes | Comma-separated list of object IDs of type ObjectType<n> |
| `[RegisterType]` | INT | No | Type of the parent register +<br>`0 = not in any register (directly on folder level)` +<br>-1 = register-independent |
| `[RegisterID]` | INT | No | ID of the parent register |
| `[FolderID]` | INT | No | ID of the folder |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `ObjectType<n>` | INT | — | nth object type |
| `ObjectList<n>` | String | — | Comma-separated list of IDs and determined rights for object type n. The object ID is separated from the determined rights by a colon. See example below. |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

> **Note:** The order of object types as well as objects in an ID list does not have to match the
order in the input parameters.

**Example call:**

```properties
Flags=0
Access=WRXDU
FolderID=380
FolderType=1
RegisterID=0
RegisterType=0
ObjectType1=393216
ObjectList1=65493
ObjectType2=131072
ObjectList2=72272,72273,72274
```
**Example return:**

```properties
ObjectType1=131072
ObjectList1=72272:RWXUD,72273:RW---,72274:R-X-
ObjectType2=393216
ObjectList2=65493:RWXUD
```

<a id="dms.ConvertQuery"></a>

## dms.ConvertQuery

This job allows conversion between various request formats.

The following formats are supported:

* `DMS` — [DMSQuery](xsd/DMSQuery.md) XML format
* `STQ` — Format for stored queries
* `ABN` — Format for subscriptions

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags must be `0` |
| `OutputUnicode` | INT | Yes | Must be `1` |
| `Query` | STRING or BASE64 | Yes | Request text |
| `InputFormat` | STRING | Yes | Input format: `DMS`, `STQ` or `ABN` |
| `OutputFormat` | STRING | Yes | Output format: `DMS`, `STQ` or `ABN` |
| `[Name]` | STRING | No | Name of the request (only for OutputFormat `STQ`) |
| `[QueryID]` | INT | No | ID of the request (only for OutputFormat `STQ`) |
| `[IconID]` | INT | No | ID of an icon that is displayed in the client. Default `0` (only for OutputFormat `STQ`) |
| `[DefAction]` | INT | No | Action when opening the stored query (only for OutputFormat `STQ`). +<br>`0` = Execute (Default), `1` = Edit, `2` = Count hits |
| `[GarbageMode]` | INT | No | `1` = Consider objects from the trash can, `0` = do not consider (Default, only for OutputFormat `ABN`) |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Query` | BASE64 | OutputFormat `DMS` | Request text in [DMSQuery](xsd/DMSQuery.md) XML format (UTF-8 encoded) |
| `sQuery` | STRING | OutputFormat `STQ` / `ABN` | Request text in target format (ANSI encoded) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

> **Note:** Since the request possibilities of the [DMSQuery](xsd/DMSQuery.md) XML format exceed those of the other
formats, the following limitations apply for the DMSQuery XML format as input format:

* Hierarchical structures are not supported (`<ParentObjects>`, `<ChildObjects>`, `<ExternalObjects>` are ignored).
* Parameter names must have the format `$VARnnn$` or `$STATnnn$` (nnn = 000–999).
* Field groups within conditions cannot be used.
* Only one value can be specified for each condition.
* Conditions for base parameters and system fields cannot be formulated.
* Stored queries (STQ) in expert mode cannot be converted.

<a id="dms.CopySD"></a>

## dms.CopySD

This job assigns a copy of the access control entries of an object to one or more
other objects. When copying, only access rights for users or user groups are transferred to the target objects for which there are no entries in the respective target object yet. Conversely, existing access rights for users for whom there are no entries in the source object are not touched.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `ObjectID` | INT | Yes | ID of the source object |
| `ObjectType` | INT | Yes | Type of the source object |
| `Destination` | STRING | Yes | List of target objects in XML format |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

> **Note:** Detailed description of Destination

* object_type: Type of the object (Object Type ID)

* object_id: ID of the object

**Building Destination**

```xml
<DMSAccess>
  <ACL object_type="XXX1" object_id="YYY1"/>
  <ACL object_type="XXX2" object_id="YYY2"/>
  <ACL object_type="XXX3" object_id="YYY3"/>
</DMSAccess>
```

<a id="dms.CreateCollaborationDocuments"></a>

## dms.CreateCollaborationDocuments

This job creates one or more collaboration shares. With a share, a user (`from_user`)
grants another user (`to_user`) certain access rights (`rights`) on a DMS object for a
limited period (`valid_from` … `valid_to`) and may attach a remark. The shares are passed
as a JSON document.

====
This job is not listed in the official enaio® DMS engine overview. This description was reconstructed from the observed call behavior. On the server, the job prefix is uppercase (`DMS.CreateCollaborationDocuments`); enaio® servers accept both spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved; always pass `0`. |
| `JSON` | BASE64 | Yes | Shares to create, in JSON format (UTF-8). Root object with key `objects`, whose value is an array of share records (fields see below). |

#### JSON record per share

* `object_id`: ID of the object
* `object_type`: Type of the object (Object Type ID)
* `from_user`: ID of the granting user
* `to_user`: ID of the user the share is granted to
* `valid_from`: Start of the share's validity in German date format (`dd.mm.yyyy`)
* `valid_to`: End of the share's validity in German date format (`dd.mm.yyyy`)
* `rights`: Granted access rights as a string composed of the letters +
R = read index data +
W = write index data +
X = open/execute object +
D = delete object +
U = write object
* `remark`: Remark by the granting user about the share

**Example**

```json
{
  "objects": [
    {
      "object_id": 2846,
      "object_type": 262148,
      "from_user": 10,
      "to_user": 74,
      "valid_from": "08.05.2026",
      "valid_to": "22.05.2026",
      "rights": "RXU",
      "remark": "test"
    }
  ]
}
```

### Return Value

`(INT)`: `0` = job successful, otherwise error code. No content output parameters are returned.

For further return values see [Error Codes](errorcodes.md).

### See Also

* [dms.GetAllCollaborationDocuments](dms.md#dms.GetAllCollaborationDocuments) — lists existing shares
* [dms.DeleteCollaborationDocumentsEx](dms.md#dms.DeleteCollaborationDocumentsEx) — deletes shares

<a id="dms.CreateOsEvent"></a>

## dms.CreateOsEvent

Creates a new OS event.

====
This job accesses the internal scripting infrastructure of enaio® directly. Incorrectly configured events can cause unexpected behavior or serious malfunctions on the client or server side.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `EventCode` | INT | Yes | Event type of the new event. +<br>Complete value description: Event code list |
| `OsClassName` | STRING | No | Target object type: `type_id` as a string or `"Application"`. +<br>Description: Field `os_class_name` |
| `OsEventParams` | STRING | No | Context parameter — content depends on `EventCode` (field GUID, job name, or library name). +<br>Mapping: `os_event_params` — Mapping |
| `VBCode` | BYTE[] | Yes | Executable script code of the event (JavaScript or VBScript). +<br>Description: Field `vb_code` |
| `AppClass` | STRING | No | Target platform: `1` = Client · `2` = Server · `3` = WebClient. +<br>Mapping: Field `app_class` |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `IsEventId` | INT | — | ID of the newly created event. Corresponds to the `id` field in the JSON response of [dms.GetOsEvents](dms.md#dms.GetOsEvents). |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.CreatePDFAnnotations"></a>

## dms.CreatePDFAnnotations

This job creates one or more PDF annotations on a DMS object.
The annotations are passed as a JSON document.

====
This job is not listed in the official enaio® DMS engine overview. This description was reconstructed from the call code of the `enaio-jobs-custom` template. On the server, the job prefix is uppercase (`DMS.CreatePDFAnnotations`); enaio® servers accept both spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved; always pass `0`. |
| `JSON` | BASE64 | Yes | Annotations to create, in JSON format (including object reference). |
| `OutputUnicode` | INT | Yes | `1` = response IDs as Unicode (`sAnnotationIds`); `0` = legacy `AnnotationIds` as bytearray in default encoding. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `sAnnotationIds` | STRING | if `OutputUnicode=1` | IDs of the created annotations as a string (e.g. comma-separated). |
| `AnnotationIds` | BASE64 | if `OutputUnicode=0` | IDs of the created annotations as a bytearray (default encoding). |

### Return Value

`(INT)`: `0` = job successful, otherwise error code.

For further return values see [Error Codes](errorcodes.md).

### Required Roles

The caller needs the following [system roles](mng.md):

* `81` — Client: View preview annotations
* `82` — Client: Edit preview annotations

### See Also

* [dms.GetPDFAnnotations](dms.md#dms.GetPDFAnnotations) — reads annotations
* [dms.UpdatePDFAnnotations](dms.md#dms.UpdatePDFAnnotations) — modifies existing annotations
* [dms.DeletePDFAnnotations](dms.md#dms.DeletePDFAnnotations) — deletes annotations

<a id="dms.CreateSD"></a>

## dms.CreateSD

This job creates a Security Descriptor for each object instance defined in the parameter 'XmlInfo'.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `XmlInfo` | STRING | Yes | List of objects in XML format for which Security Descriptors should be created |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Building the input parameter XmlInfo**

```xml
<DMSAccess>
  <ACL obj_type="1" obj_id="61967"/>
  <ACL obj_type="1" obj_id="61968"/>
</DMSAccess>
```
**Returned ACL list in XML format (Description: see ACL XML Schema)**

```xml
<DMSAccess timestamp="2004-04-08T12:59:25" version="4.50">
  <ACL ossd="6DBEC785D3CEB4D894B" obj_type="1" obj_id="61967"/>
  <ACL ossd="2AB8AB82E0CEB4D8BDD" obj_type="1" obj_id="61968"/>
</DMSAccess>
```

### See Also

[dms.SetSD](dms.md#dms.SetSD)

<a id="dms.DelPortfolio"></a>

## dms.DelPortfolio

This job deletes a folder. The folder to be deleted can be identified either by the folder ID or by
recipient (recipient/recipient_id) and the title (subject) of the folder.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `PortfolioXML` | BASE64 | Yes | Description of the folder in XML format |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Building PortfolioXML (Description: see Portfolio XML Format)**

```xml
<Portfolio>
</Portfolio>
<!-- or -->
<Portfolio>
</Portfolio>
```

<a id="dms.DeleteCollaborationDocumentsEx"></a>

## dms.DeleteCollaborationDocumentsEx

This job deletes one or more collaboration shares. The shares to delete are passed as a
JSON document in the same format as for
[dms.CreateCollaborationDocuments](dms.md#dms.CreateCollaborationDocuments) — a record
is identified by the combination of `object_id`, `object_type`, `from_user`, and `to_user`.

====
This job is not listed in the official enaio® DMS engine overview. This description was reconstructed from the observed call behavior. On the server, the job prefix is uppercase (`DMS.DeleteCollaborationDocumentsEx`); enaio® servers accept both spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved; always pass `0`. |
| `JSON` | BASE64 | Yes | Shares to delete, in JSON format (UTF-8). Root object with key `objects`, whose value is an array of share records; fields identical to [dms.CreateCollaborationDocuments](dms.md#dms.CreateCollaborationDocuments) (`object_id`, `object_type`, `from_user`, `to_user`, `valid_from`, `valid_to`, `rights`, `remark`). |
**Example**

```json
{
  "objects": [
    {
      "object_id": 2846,
      "object_type": 262148,
      "from_user": 10,
      "to_user": 74,
      "valid_from": "08.05.2026",
      "valid_to": "22.05.2026",
      "rights": "RXU",
      "remark": "test"
    }
  ]
}
```

### Return Value

`(INT)`: `0` = job successful, otherwise error code. No content output parameters are returned.

For further return values see [Error Codes](errorcodes.md).

### See Also

* [dms.CreateCollaborationDocuments](dms.md#dms.CreateCollaborationDocuments) — creates new shares
* [dms.GetAllCollaborationDocuments](dms.md#dms.GetAllCollaborationDocuments) — lists existing shares

<a id="dms.DeleteOsEvent"></a>

## dms.DeleteOsEvent

Deletes an OS event by its ID.

====
This job accesses the internal scripting infrastructure of enaio® directly. Incorrectly configured events can cause unexpected behavior or serious malfunctions on the client or server side.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `OsEventID` | INT | Yes | ID of the event to delete. Corresponds to the `id` field in the JSON response of [dms.GetOsEvents](dms.md#dms.GetOsEvents). |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.DeletePDFAnnotations"></a>

## dms.DeletePDFAnnotations

This job deletes one or more PDF annotations from a DMS object.
The annotations to delete are passed as a JSON document (typically containing only IDs).

====
This job is not listed in the official enaio® DMS engine overview. This description was reconstructed from the call code of the `enaio-jobs-custom` template. On the server, the job prefix is uppercase (`DMS.DeletePDFAnnotations`); enaio® servers accept both spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved; always pass `0`. |
| `JSON` | BASE64 | Yes | Annotations to delete, in JSON format (at minimum their IDs). |

### Return Value

`(INT)`: `0` = job successful, otherwise error code.

For further return values see [Error Codes](errorcodes.md).

### Required Roles

The caller needs the following [system roles](mng.md):

* `81` — Client: View preview annotations
* `82` — Client: Edit preview annotations

### See Also

* [dms.CreatePDFAnnotations](dms.md#dms.CreatePDFAnnotations) — adds new annotations
* [dms.UpdatePDFAnnotations](dms.md#dms.UpdatePDFAnnotations) — modifies existing annotations
* [dms.GetPDFAnnotations](dms.md#dms.GetPDFAnnotations) — reads annotations

<a id="dms.DeleteSD"></a>

## dms.DeleteSD

With this job, the access control entry of a user/group or the entire
access control list for a specified object can be deleted.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Controls what is deleted: +<br>`0` — Object via `ObjectType`/`ObjectID`: the entire Security Descriptor (all ACEs) will be deleted. +<br>`1` — Object via `Ossd`: all ACEs of the user/group specified by `Osuid` will be deleted. +<br>`2` — Object via `ObjectType`/`ObjectID`: all ACEs of the user/group specified by `Osuid` will be deleted. |
| `[ObjectType]` | INT | No | Type of the object (for Flags `0` or `2`) |
| `[ObjectID]` | INT | No | ID of the object instance (for Flags `0` or `2`) |
| `[Ossd]` | STRING | No | GUID of the Security Descriptor (for Flags `1`) |
| `[Osuid]` | STRING | No | GUID of the user/group whose access rights should be deleted (for Flags `1` or `2`) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.DeleteUserData"></a>

## dms.DeleteUserData

This job deletes the user-related data record specified by name and type.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `Type` | INT | Yes | see data types |
| `Name` | STRING | Yes | Identifier of the data record |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.ExecuteStoredQuery"></a>

## dms.ExecuteStoredQuery

This job executes stored queries. The result is returned in the DMS Content
format.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags to control the output format +<br>`0x00000010 (16) = XML result is returned as a file, otherwise as a buffer` +<br>`0x00001000 (4096) = XML result is encoded in UTF-8, otherwise UTF-16` |
| `QueryID` | INT | Yes | ID of the query |
| `[CheckParams]` | INT | No | `0` = If no value is defined for a request parameter, conditions that reference this parameter are ignored (Default). +<br>`1` = An error message is generated if a referenced parameter is not defined. |
> **Note:** If it is a parametrized query, the query parameters must be passed as job parameters.
The `$` characters that surround the parameters in the query must be omitted (e.g. `VAR1` or `STAT3`).
The parameter `QueryCatalogueLocale` can be used to control in which language multilingual catalogs are passed as query parameters.
Additionally, the following parameters can be set to format the returned XML document:
`RequestType`, `OutputFormat`, `BaseParams`, `Offset`, `Pagesize`, `MaxHits`, `Rights`, `DateFormat`, `Variants`, `FileInfo`, `Baseparams`.
The description of these parameters can be found in the description of the job [dms.GetResultList](dms.md#dms.GetResultList).

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Count` | INT | — | Number of records returned |
| `TotalHits` | INT | — | Number of available hits |
| `[XML]` | BASE64 | Optional | Hit list in [DMSContent](xsd/DMSContent.md) XML format (when Flags is not `0x00000010 (16)`) |

### Output Files

| Name | Description |
|---|---|
| `[FileCount]` | Only one file is always returned |
| `[File list]` | Name and path of the [DMSContent](xsd/DMSContent.md) XML file containing the hit list |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.GetAllCollaborationDocuments"></a>

## dms.GetAllCollaborationDocuments

This job returns all collaboration shares present in the system — incoming and outgoing,
across all users — as a JSON document. The format and fields of the records correspond to
those of [dms.CreateCollaborationDocuments](dms.md#dms.CreateCollaborationDocuments).

====
This job is not listed in the official enaio® DMS engine overview. This description was reconstructed from the observed call behavior. On the server, the job prefix is uppercase (`DMS.GetAllCollaborationDocuments`); enaio® servers accept both spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved; always pass `0`. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `JSON` | BASE64 | — | Existing shares in JSON format (UTF-8). Root object with key `objects`, whose value is an array of share records; fields identical to [dms.CreateCollaborationDocuments](dms.md#dms.CreateCollaborationDocuments) (`object_id`, `object_type`, `from_user`, `to_user`, `valid_from`, `valid_to`, `rights`, `remark`). |
**Example**

```json
{
  "objects": [
    {
      "object_id": 2846,
      "object_type": 262148,
      "from_user": 10,
      "to_user": 74,
      "valid_from": "08.05.2026",
      "valid_to": "22.05.2026",
      "rights": "RXU",
      "remark": "test"
    }
  ]
}
```

### Return Value

`(INT)`: `0` = job successful, otherwise error code.

For further return values see [Error Codes](errorcodes.md).

### See Also

* [dms.CreateCollaborationDocuments](dms.md#dms.CreateCollaborationDocuments) — creates new shares
* [dms.DeleteCollaborationDocumentsEx](dms.md#dms.DeleteCollaborationDocumentsEx) — deletes shares

<a id="dms.GetCheckedOutDocuments"></a>

## dms.GetCheckedOutDocuments

This job returns all documents that have been checked out by the currently logged-in user.
Documents in the trash are not returned. Inactive variants are
also returned.

The `Info` parameter contains all records separated by semicolons.
A record provides the following information separated by commas:

* Type ID
* Document ID
* Timestamp of checkout time
* Active variant ID (If the document is the active variant, it is the document ID, otherwise the active variant)

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | reserved, must be `0` |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Info` | STRING | — | Semicolon-separated list of checked-out documents. Each entry contains: Type ID, Document ID, Timestamp, active variant ID (comma-separated). |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.GetConfValues"></a>

## dms.GetConfValues

This job returns configuration values from the server-side DMS INI files.
For each requested configuration type, a set of numbered output parameters (`sConfValue_0`, `sConfValue_1`, …) is returned.

====
This job is not listed in the official enaio® DMS engine overview. This description was reconstructed from the call code of the `enaio-jobs-custom` template.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved; always pass `0`. |
| `ConfTypes` | STRING | Yes | Comma-separated list of numeric configuration type codes (e.g. `"3"` for the DMS INI). |
| `OutputUnicode` | INT | Yes | `1` = string values as Unicode (`sConfValue_<n>`); `0` = legacy as bytearray (`ConfValue_<n>`, default `cp1252` encoding). |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Count` | INT | — | Number of configuration values returned. |
| `sConfValue_<n>` | STRING | if `OutputUnicode=1` | Unicode variant of the `n`-th configuration value (`n` from `0` to `Count-1`). |
| `ConfValue_<n>` | BASE64 | if `OutputUnicode=0` | Bytearray variant of the `n`-th configuration value (default encoding `cp1252`). |

### Return Value

`(INT)`: `0` = job successful, otherwise error code.

For further return values see [Error Codes](errorcodes.md).

### See Also

* [krn.REGetRegValue](krn.md#krn.REGetRegValue) — reads a single registry entry
* [krn.REGetRegValues](krn.md#krn.REGetRegValues) — reads all registry values under a key

<a id="dms.GetDeletedObjects"></a>

## dms.GetDeletedObjects

This job can be used to output the content of the logged-in user's trash bin. The
result is returned in the DMS Content format. The same output format options
apply as for the job [dms.GetResultList](dms.md#dms.GetResultList).

A search within the trash can can also be performed. For this, a request
must be formulated in [DMSQuery](xsd/DMSQuery.md) XML format and passed as the `XML` parameter.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags to control the output format +<br>`0x00000010 (16) = XML result is returned as a file, otherwise as a buffer` +<br>`0x00001000 (4096) = XML result is encoded in UTF-8, otherwise UTF-16` |
| `[UserID]` | INT | No | ID of the user whose trash can is to be read. With the value -1 the entire system trash can is read, the default value 0 denotes the logged-in user. To read the system trash can or the trash can of another user, the [system role](mng.md) `Client: Show system trash can` is required, otherwise an 'Access denied' error code (-1069) is returned. |
| `[XML]` | BASE64 | No | Request in [DMSQuery](xsd/DMSQuery.md) format (search in the trash can) |
| `[CheckParams]` | INT | No | 0 = If no value is defined for a request parameter, conditions that reference this parameter are ignored. This is the default value. 1 = An error message is generated if a referenced parameter is not defined. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Count` | INT | — | Number of records returned |
| `TotalHits` | INT | — | Number of available hits |
| `[XML]` | BASE64 | Optional | Hit list in [DMSContent](xsd/DMSContent.md) XML format (when Flags is not `0x00000010 (16)`) |

### Output Files

| Name | Description |
|---|---|
| `[FileCount]` | Only one file is always returned |
| `[File list]` | Name and path of the [DMSContent](xsd/DMSContent.md) XML file containing the hit list |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.GetForeignObjects"></a>

## dms.GetForeignObjects

With this job, all objects that have a document reference to a given object can be determined (aka. green arrow reference). The result is returned in the DMS Content format.
The same output format options apply as for the job [dms.GetResultList](dms.md#dms.GetResultList).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags for controlling the output format +<br>`0x00000010 (16) = XML result is returned as a file, otherwise as a buffer` |
| `ObjectID` | INT | Yes | ID of the target object whose document references should be displayed. The target object ID of the green arrow reference. |
| `[ObjectTypes]` | STRING | No | A semicolon-separated list of reference types. If this parameter is not set, search is performed in all types in all cabinets. The reference type can be passed as a type ID or as the internal name of the type. If an archive (cabinet) is passed as a type, all contained document types are used as source types. +<br>Example: `ObjectTypes=1;interne_email;262432` |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `TotalHits` | INT | — | Number of visible document reference objects to the target object. |
| `TotalForeignObjects` | INT | — | Complete number of document references to the target object. When determining the number, the security system is not taken into account. If the input parameter `ObjectTypes` was used, only the number of references found in the given types is returned. |
| `[Result]` | BASE64 | Optional | Object list in [DMSContent](xsd/DMSContent.md) XML format (when Flags is not `0x00000010 (16)`) |

### Output Files

| Name | Description |
|---|---|
| `[FileCount]` | Only one file is always returned |
| `[File List]` | Name and path of the [DMSContent](xsd/DMSContent.md) XML file containing the hit list |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

> **Note:** The job supports the same input parameters as
[dms.GetObjectDetails](dms.md#dms.GetObjectDetails) or
[dms.GetResultList](dms.md#dms.GetResultList).

<a id="dms.GetObjDef"></a>

## dms.GetObjDef

This job returns all object definitions in XML format.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Options for this job Visibility is checked independently of the object flag 'ignore security system'. +<br>`1 = Object definition is returned via parameter sRet, otherwise as XML file` +<br>`2 = Visible cabinets and objects are output, but no field information. The` +<br>`4 = Images of the object definition are output encoded in BASE64 in the XML return.` +<br>`4096 = the XML document is encoded in UTF-8, otherwise UTF-16` |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `[sRet]` | BASE64 | Optional | Object definition in XML format |

### Output Files

| Name | Description |
|---|---|
| `[FileCount]` | 1 = Output file was successfully created, otherwise 0 |
| `[FileList]` | Name and path of the XML file containing the object definition |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Object definitions in XML format**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<asobjdef version="4.00">
  <OS4x/>
  <languages>
    <language/>
  </languages>
  <cabinet>
    <object kisearchindex="1" no_dias="0" referencetype="0" fulltext="0" apply_security="0" multidoc="0">
      <names>
        <name/>
      </names>
      <fields>
        <field>
          <names>
            <name/>
          </names>
          <ids/>
          <flags align="left" dt="A" input_length="0" readonly="supervisor" multifield="0" zeropad="0" control_type="edit" datatype="text" constraints="none" required="0" crosscheck="0" case="0"/>
          <field_pos bottom="0" left="0" right="0" top="0"/>
          <input_pos bottom="0" left="0" right="0" top="0"/>
          <init func="0" init_type="const"/>
          <list multiselection="0" order="0">
            <rawdata/>
            <extra/>
            <row/>
          </list>
          <page/>
        </field>
      </fields>
      <ids/>
      <frame bottom="0" left="0" right="0" top="0"/>
      <multiframe/>
    </object>
  </cabinet>
</asobjdef>
```

<a id="dms.GetObjectDetails"></a>

## dms.GetObjectDetails

This job can be used to determine the index data of a single DMS object. The location is irrelevant.
Data of inactive variants can also be determined this way. The result is returned in the [DMSContent HOL Format](xsd/DMSContent.md). All input parameters that can be specified for the job
[dms.GetResultList](dms.md#dms.GetResultList) to influence the output information can also be used analogously for GetObjectDetails.

For this job, the request property [FollowDocLink] is set to '1' by default, if it is not explicitly disabled by the job parameter.
This means that in the default case, the document properties of the linked DMS object are returned when [FileInfo] is requested,
if it is a document link object (see File Information).

When variants are requested (Variants=1), the desired fields can be specified via internal names (VariantFields)
and the base parameters (VariantSystemFields) can also be requested.

Base parameters:
[OBJECT_CRDATE](reference/dms_reference.md);
[OBJECT_CRID](reference/dms_reference.md);
[OBJECT_MODIFYUSER](reference/dms_reference.md);
[OBJECT_MODIFYTIME](reference/dms_reference.md);
[OBJECT_RETENTION_PLANNED](reference/dms_reference.md);
[OBJECT_RETENTION](reference/dms_reference.md);
[OBJECT_AVDATE](reference/dms_reference.md);
[OBJECT_AVID](reference/dms_reference.md);
[OBJECT_TIME](reference/dms_reference.md);
[OBJECT_DOCPAGECOUNT](reference/dms_reference.md)

> **Important:** The system fields [SDSTA_ID](reference/dms_reference.md), [SDREG_ID](reference/dms_reference.md), and [SDREG_TYPE](reference/dms_reference.md) are **not** supported by this job and will cause errors if used. If these fields are required, the job [dms.GetResultList](dms.md#dms.GetResultList) must be used instead.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ObjectID` | INT | Yes | The ID of the object instance |
| `[ObjectType]` | INT | No | Type of the object. If this parameter is not specified or specified with the value -1, the job itself determines the object type. |
| `[SystemFields]` | String | No | Semi-colon separated list of additionally requested system fields. Internal names of system fields are expected (see System Fields). If base parameters are requested, these have preference, i.e. the information requested with SystemFields appears in the respective result block in the return result (e.g. within <baseparams>) and is not returned redundantly. Not all system fields are supported by this job — whether a system field is supported is documented in the System Field Reference. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `XML` | BASE64 | — | Index data in [DMSContent](xsd/DMSContent.md) XML format |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

> **Note:** Additional possible parameters: See job [dms.GetResultList](dms.md#dms.GetResultList).

**Example for SystemFields request:**

```properties
SystemFields=OBJECT_MEDDOCID;OBJECT_MEDDOCNA
```

### Related Jobs

* [dms.GetResultList](dms.md#dms.GetResultList) — Search for multiple objects; returns the same [DMSContent HOL format](xsd/DMSContent.md) and shares all output parameters

<a id="dms.GetObjectHistory"></a>

## dms.GetObjectHistory

This job returns the editing history of a given object in XML format.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags must be `0` |
| `ObjectID` | INT | Yes | ID of the object |
| `[LangID]` | INT | No | Language in which the action descriptions should be output. +<br>Action descriptions are available in German (`7`), English (`9`) and French (`12`). +<br>If this parameter is not specified or the language is not available, German is used as the default language. |
| `[Encoding]` | STRING | No | XML encoding for the result. Allowed are `UTF-16` (Default) and `UTF-8`. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `History` | BASE64 | — | Editing history in XML format. The response is returned as a **UTF-16**-encoded byte string. |

### XML Structure of the History

#### Example

```xml
<?xml version="1.0" encoding="UTF-16" standalone="yes"?>
<DMSHistory exec_version="12.0.769.25242" timestamp="09.04.2026 10:47:20">
  <Modification osguid="278D932B28F34F1B97CC5B87F6B37AF9">
    <Time>09.04.2026 10:40:27</Time>
    <Action id="3">Index data modified</Action>
    <Description>The object's index data or its status has been modified using client functions or by carrying out an update as part of the import operation.</Description>
    <UserNameShort>ROOT</UserNameShort>
    <UserNameFull>Administrator</UserNameFull>
    <Station station_id="C7377EEAAE0A4486A97AAE671EA82A4E">ECM4</Station>
    <Info>Index data modified</Info>
  </Modification>
  <Modification osguid="11EB572C8C4E4FAFB66181AF16D3BD4B">
    <Time>15.08.2025 14:54:19</Time>
    <Action id="2">Object created</Action>
    <Description>The specified object was created using client functions or via an import operation.</Description>
    <UserNameShort>ROOT</UserNameShort>
    <UserNameFull>Administrator</UserNameFull>
    <Station station_id="C7377EEAAE0A4486A97AAE671EA82A4E">ECM4</Station>
    <Info>Object created</Info>
  </Modification>
</DMSHistory>
```

#### `<DMSHistory>` — Root Element

| Attribute | Type | Description |
|---|---|---|
| `exec_version` | STRING | Version number of the executing server (e.g. `12.0.769.25242`). |
| `timestamp` | STRING | Timestamp of the query in the format `DD.MM.YYYY HH:MM:SS`. |

#### `<Modification>` — Single History Entry

Repeating child element of `<DMSHistory>`. Entries are sorted in descending chronological order (most recent first).

| Attribute | Type | Description |
|---|---|---|
| `osguid` | STRING | Unique GUID of the history entry (32 hex characters, without hyphens). |
Child elements:

| Element | Type | Description |
|---|---|---|
| `<Time>` | STRING | Timestamp of the modification in the format `DD.MM.YYYY HH:MM:SS`. |
| `<Action id="...">` | STRING (text) / INT (attribute) | Localized short name of the action. The `id` attribute contains the numeric action ID (see <<Actions>>). |
| `<Description>` | STRING | Localized long description of the action. |
| `<UserNameShort>` | STRING | Internal username (login name, e.g. `ROOT`). |
| `<UserNameFull>` | STRING | Display name of the user (e.g. `Administrator`). |
| `<Station station_id="...">` | STRING (text) / STRING (attribute) | Hostname of the workstation. The `station_id` attribute contains the GUID of the station. |
| `<Info>` | STRING | Additional information about the action. |
> **Note:** `<Action>`, `<Description>` and `<Info>` are localized in the language selected via `LangID`. Entries are sorted in descending order by timestamp — the most recent entry appears first.

### Actions

The following table lists all possible action types that can appear in the editing history:

| ID | Name | Description |
|---|---|---|
| `1` | `ELECTRONIC_SIGNATURE` | The document has been electronically signed. |
| `2` | `OBJECT_CREATED` | The object was created using client functions or via an import operation. |
| `3` | `INDEX_DATA_MODIFIED` | The object's index data or its status has been modified. |
| `4` | `CONTENT_CHANGED` | The document content was edited via client functions or an import update. |
| `5` | `DOCUMENT_ARCHIVED` | The document was archived in a legally compliant manner. |
| `6` | `DOCUMENT_DELETED` | The document was deleted. |
| `7` | `OUTPUT_CONTENT` | The document content was read, printed, or otherwise output without changes. |
| `8` | `DOCUMENT_STATUS_APPROVED` | The document's status was set to 'Approved for archiving'. |
| `9` | `DOCUMENT_STATUS_NOT_APPROVED` | The document's status was set to 'Not approved for archiving'. |
| `10` | `DOCUMENT_CREATED` | The object was created using client functions or via an import operation. |
| `11` | `LINK_CREATED` | The document was linked via notes to another object. |
| `12` | `LINK_REMOVED` | An existing link to another object has been removed. |
| `13` | `SQL_QUERY` | Data was requested via SQL. |
| `14` | `SQL_COMMAND` | Data was modified via SQL. |
| `15` | `ELECTRONIC_SIGNATURE_ADDED` | An electronically signed document was marked with another signature. |
| `16` | `SIGNED_DOCUMENT_DELETED` | The signed document was deleted. |
| `17` | `VERSION_CREATED` | A version was created for the document. |
| `18` | `VERSION_DELETED` | A version of the document was deleted. |
| `19` | `RESTORED_FROM_VERSION` | The document was restored from a previous version. |
| `20` | `FULLTEXT_QUERY` | The database was searched using a full-text query. |
| `21` | `DOCUMENT_MOVED` | The document location was changed. |
| `22` | `REGISTER_MOVED` | The register location was changed. |
| `23` | `FOLDER_MERGED_FROM` | Objects in the folder were merged from another folder. |
| `24` | `FOLDER_MERGED_TO` | Objects in the folder were moved to another folder. |
| `25` | `REGISTER_MERGED_FROM` | Objects in the register were merged from another register. |
| `26` | `REGISTER_MERGED_TO` | Objects in the register were moved to another register. |
| `27` | `OBJECT_MARKED_FOR_DELETION` | The object was moved to the recycle bin. |
| `28` | `OBJECT_RECOVERED` | The object has been restored from the recycle bin. |
| `29` | `OBJECT_IRREVOCABLY_DELETED` | The object was deleted and cannot be restored. |
| `30` | `NOTICE_CONFIRMED` | The user has acknowledged the document's content. |
| `31` | `OBJECT_INFORMATION` | Log entry from the business model. |
| `32` | `OWNER_CHANGED` | Ownership of the object was transferred to another user. |
| `33` | `VARIANT_ACTIVATED` | The document was defined as the active variant. |
| `34` | `VARIANT_DEACTIVATED` | The 'active variant' status was deactivated. |
| `35` | `VARIANT_DELETED` | A variant of the document was deleted. |
| `36` | `VARIANT_CREATED` | A variant of the document was created. |
| `37` | `TYPE_ASSIGNED` | An object type was assigned to an object without a type. |
| `38` | `MOVED_FROM_FILING_TRAY` | The document location was changed from the filing tray to a folder or register. |
| `39` | `NEW_LOCATION_ADDED` | A new location was added to this document. |
| `40` | `USER_INFORMATION` | Additional information entered by user. |
| `41` | `RETENTION_TIME_SET` | The retention time was set during archiving or while increasing the retention time. |
| `42` | `DOCUMENT_DEARCHIVED` | The document was dearchived. |
| `43` | `DOCUMENT_TYPE_MODIFIED` | The document type was modified. |
| `44` | `PREVIEW_ANNOTATION_CREATED` | A preview annotation was created for this document. |
| `45` | `PREVIEW_ANNOTATION_CHANGED` | A preview annotation was changed. |
| `46` | `PREVIEW_ANNOTATION_DELETED` | A preview annotation was deleted. |
| `47` | `NOTICE_CONFIRMED_BY_PASSWORD` | The confirmation of notice was confirmed by the user by entering a password. |
| `48` | `DOCUMENT_SHARE_CREATED` | This document was shared with other users for editing or in read-only mode. |
| `49` | `DOCUMENT_SHARE_MODIFIED` | This document share was modified. |
| `50` | `DOCUMENT_SHARE_DELETED` | This document share was deleted. |
| `51` | `CREATED_FROM_COPY` | This object was created as a copy of another object. |
| `52` | `REMOVED_FROM_LOCATION` | This object was removed from a location. |
| `53` | `ACTIVE_VARIANT_STATUS_CHANGED` | The 'active variant' status has been changed in variant administration. |
| `54` | `ADDITIONAL_VARIANT_CREATED` | Another variant has been created in variant administration. |
| `55` | `DOCUMENT_COLLABORATIVE_EDITING` | The user has participated in the collaborative editing of this document. |
| `56` | `DOCUMENT_EDITED_EXTERNALLY` | A user has edited the document content via an external application. |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

> **Note:** If the user was deleted in the meantime, `UserNameShort` and `UserNameFull` are not filled in the result.

<a id="dms.GetObjectTypeByID"></a>

## dms.GetObjectTypeByID

This job allows determining the type of an object instance.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved. Must be `0`. |
| `ObjectID` | INT | Yes | ID of the object instance |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `ObjectType` | INT | — | Type of the object. Consists of a main type (Highword) and a subtype (Lowword). |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

.Supported object types:
| Object type | Main type | Subtype |
|---|---|---|
| Folder | `0` | `>=0` |
| Cabinet | `99` | `>=0` |
| Document — Grayscale | `1` | `>=0` |
| Document — Black/White | `2` | `>=0` |
| Document — Color | `3` | `>=0` |
| Document — Windows | `4` | `>=0` |
| Document — Multimedia | `5` | `>=0` |
| Document — E-Mail | `6` | `>=0` |
| Document — XML | `7` | `>=0` |
| Document — Container | `8` | `>=0` |
| Typeless document in user tray | `200` | `1`–`7` (see document main type) |
| Typeless document in workflow tray | `300` | `1`–`7` (see document main type) |
| Portfolio | `203` | `0` |
| Note | `32767` | `1`–`4` |

<a id="dms.GetObjectsByDigest"></a>

## dms.GetObjectsByDigest

This job returns object information based on a hash value (fingerprint) for any file. It can be used to determine whether a file has already been stored in the system. The job uses the '[std.FindDocumentDigest](std.md#std.FindDocumentDigest)' job internally, but performs an additional validity check afterwards. The input parameter 'Digest' is a fingerprint of the file that can be determined using the SHA2-256 algorithm. Helper functions are available in the respective client libraries to determine the digest from a file without having to transfer the file to the server.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags must be 0 |
| `Digest` | String | Yes | Hash value of the file whose presence should be checked. (SHA2-256Bit) |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `TotalHits` | INT | — | Number of hits |
| `ObjectIds` | String | — | Comma-separated list of object IDs of the found documents. |
| `TypeIds` | String | — | Comma-separated list of object types. |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.GetOsEvents"></a>

## dms.GetOsEvents

Retrieves OS events from enaio®. All input parameters are optional filters — if multiple are specified, they are combined with AND. Without filter parameters, all events are returned.

The return format is described under JSON structure, the complete field reference under Fields.

====
This job accesses the internal scripting infrastructure of enaio® directly. Incorrectly configured events can cause unexpected behavior or serious malfunctions on the client or server side.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ID` | STRING | No | Filters by the database primary key (`id`) of the event |
| `EventCode` | STRING | No | Filters by the event type (`event_code`). +<br>Complete value description: Event code list |
| `OsClassName` | STRING | No | Filters by the target object type (`os_class_name`): `type_id` as a string or `"Application"` |
| `ObjectClass` | STRING | No | Filters by the UI context (`object_class`). +<br>Complete mapping: object_class — Mapping |
| `AppClass` | STRING | No | Filters by the target platform (`app_class`): `1` = Client · `2` = Server · `3` = WebClient |
| `EventParams` | STRING | No | Filters by the context parameter (`os_event_params`): field GUID, job name, or library name. +<br>Complete mapping: os_event_params — Mapping |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `JSON` | STRING | — | BASE64-encoded JSON string with the retrieved events. +<br>Format: JSON structure |
| `Count` | INT | — | Number of events returned |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.GetOsMimetypes"></a>

## dms.GetOsMimetypes

This job returns the mime type information from the database.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags must be `0` |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Result` | BASE64 | — | Mime type information in XML format |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Example of returned mime type list:**

```xml
<OsMimetypes>
  <OsMimetype mimetypeid="1" mimetype="image/x-ms-bmp" mimetypegroup="IMAGE" extension="bmp" osiconid="1073743984"/>
  <OsMimetype mimetypeid="2" mimetype="image/jpeg" mimetypegroup="IMAGE" extension="jpg" osiconid="1073743984"/>
  [...]
</OsMimetypes>
```

<a id="dms.GetPDFAnnotationInfo"></a>

## dms.GetPDFAnnotationInfo

This job returns an integer-encoded info value about the PDF annotations present on a DMS
document. Which value is returned is controlled by the `InfoType` parameter — typically an
indicator or counter (e.g. "number of annotations" or "persistent PDF annotation layer
present").

The job is the lightweight counterpart to
[dms.GetPDFAnnotations](dms.md#dms.GetPDFAnnotations), which returns the full
annotation content. Typical use: check up front whether a document has annotations without
having to fetch the full content (e.g. for tab icons or badges in the document view).

====
This job is not listed in the official enaio® DMS engine overview. On the server the job
prefix is written in upper case (`DMS.GetPDFAnnotationInfo`); enaio® servers accept both
spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ObjectId` | INT | Yes | Numeric ID of the DMS document. |
| `InfoType` | INT | Yes | Selector for the info value to return. Default: `1`. |
| `UserIdent` | INT | Yes | Numeric user ID of the caller; used for the permission check. |
| `Flags` | INT | Yes | Reserved; always pass `0`. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Value` | INT | — | Requested info value. The meaning depends on the input `InfoType`. `0` typically means<br>"no annotations present" or "indicator not set". |

### Return Value

`(INT)`: `0` = job successful, otherwise error code (e.g. object does not exist, missing
permission).

For further return values see [Error Codes](errorcodes.md).

### Required Roles

The caller needs the following [system role](mng.md):

* `81` — Client: View preview annotations

### Notes

* Read-only — the job modifies neither annotations nor object data.
* In contrast to [dms.GetPDFAnnotations](dms.md#dms.GetPDFAnnotations) (which
transfers the full JSON content), this job returns only a single integer and is intended
for high-frequency indicator queries.

### Related Jobs

* [dms.GetPDFAnnotations](dms.md#dms.GetPDFAnnotations) — returns the full PDF
annotation content as JSON
* [dms.CreatePDFAnnotations](dms.md#dms.CreatePDFAnnotations) — creates new PDF
annotations
* [dms.UpdatePDFAnnotations](dms.md#dms.UpdatePDFAnnotations) — updates existing
annotations
* [dms.DeletePDFAnnotations](dms.md#dms.DeletePDFAnnotations) — deletes annotations

<a id="dms.GetPDFAnnotations"></a>

## dms.GetPDFAnnotations

This job returns the PDF annotations stored for a DMS object as a JSON document.

====
This job is not listed in the official enaio® DMS engine overview. This description was reconstructed from the call code of the `enaio-jobs-custom` template. On the server, the job prefix is uppercase (`DMS.GetPDFAnnotations`); enaio® servers accept both spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved; always pass `0`. |
| `ObjectId` | INT | Yes | Numeric ID of the DMS object. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `JSON` | BASE64 | — | List of annotations in JSON format. Encoding is chosen by the caller (typically `UTF-8` or system default). |

### Return Value

`(INT)`: `0` = job successful, otherwise error code.

For further return values see [Error Codes](errorcodes.md).

### Required Roles

The caller needs the following [system role](mng.md):

* `81` — Client: View preview annotations

### See Also

* [dms.CreatePDFAnnotations](dms.md#dms.CreatePDFAnnotations) — adds new annotations
* [dms.UpdatePDFAnnotations](dms.md#dms.UpdatePDFAnnotations) — modifies existing annotations
* [dms.DeletePDFAnnotations](dms.md#dms.DeletePDFAnnotations) — deletes annotations

<a id="dms.GetResultList"></a>

## dms.GetResultList

Searches for DMS objects that match the request.
The specification of target objects and fields is done via an [DMSQuery](xsd/DMSQuery.md) XML request document,
which can use OS names, internal names, GUIDs, and database names.

General request properties can be set both as job parameters and as
XML attributes in the root element of the XML request — XML attributes have priority.

> **Note:** The `internal_name` attribute of the [`<Archive>`](xsd/DMSQuery.md) element
is only required for cross-archive queries (multiple `<Archive>` elements) — provided that
the contained `<ObjectType>` elements also use `internal_name`.
In single-archive queries, the attribute can be omitted.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Controls the output format. +<br>`0x00000010 (16)` — Result XML is returned as a file, otherwise as a buffer. |
| `XML` | BASE64 | Yes | Request in XML format (see <<dms-getresultlist-description, Detailed Description>>). |
| `[Encoding]` | STRING | No | Encoding of the result document. +<br>Allowed values: `UTF-8`, `UTF-16`. Default: `UTF-16`. |
| `[Offset]` | INT | No | Offset for the first returned record. Default: `0`. +<br>(see <<dms-getresultlist-paging,Paging through hit lists>>) |
| `[PageSize]` | INT | No | Number of records to return. `-1` = All (Default). +<br>(see <<dms-getresultlist-paging,Paging through hit lists>>) |
| `[MaxHits]` | INT | No | Maximum hit count per object type. `-1` = All (Default), `0` = do not determine. +<br>High values can affect performance. +<br>(see <<dms-getresultlist-paging,Paging through hit lists>>) |
| `[Sql]` | INT | No | `1` — SQL statements are written to the result document (only LOL). Default: `0`. |
| `[Rights]` | INT | No | `1` — Access rights (Open/Delete/Write) are determined per object instance (HOL). Default: `0`. +<br>(see <<dms-getresultlist-rights,Rights>>) |
| `[ObjectInserts]` | INT | No | `1` — Number of insertable objects per object type is determined. Default: `0`. +<br>(see <<dms-getresultlist-rights,Rights>>) |
| `[DateFormat]` | STRING | No | Formatting of returned date values +<br>(see Date Formats). |
| `[RegisterContext]` | INT | No | `0` — For register clauses only objects in registers are requested (HOL). +<br>`1` — Default (see <<dms-getresultlist-request-behavior,General Request Behavior>>). |
| `[RequestType]` | STRING | No | Request type: `LOL`, `INF` or `HOL`. |
| `[OutputFormat]` | STRING | No | Output format depending on request type: `LOL`, `HOL` or `TXT`. +<br>(see <<dms-getresultlist-output-formats,Output Formats>>) |
| `[ItemDelimiter]` | STRING | No | Delimiter between values in a linear list as a simple text file. +<br>(see <<dms-getresultlist-output-formats,Output Formats>>) |
| `[OutputUnicode]` | INT | No | `1` — Returned file in text format is delivered as Unicode instead of ANSI. +<br>(see Parameter `Encoding`) |
| `[FieldSchema]` | STRING | No | Standard field schema for all object types of the request. +<br>Allowed values: `MIN` (only object ID), `ALL` (all index fields), `DEF` (user-defined). +<br>Can be overridden in the request document by the `field_schema` attribute in `<Fields>`, `<ParentObjects>` or `<ChildObjects>`. |
| `[Baseparams]` | INT | No | `1` — Base parameters are returned; for HOL as own XML structure. Default: `0`. +<br>(see <<dms-getresultlist-base-parameters,Base Parameters>>) |
| `[FileInfo]` | INT | No | `1` — File size, file extension and MIME type of document files are determined. +<br>(see <<dms-getresultlist-file-info,File Information>>) |
| `[FollowDocLink]` | INT | No | `1` — File information of the linked document is returned (document links with green arrow). +<br>Only effective if `FileInfo=1`. May affect performance. |
| `[Variants]` | INT | No | `1` — Variant tree is returned if multiple variants of the document exist. +<br>(see <<dms-getresultlist-variants,Document Variants>>) |
| `[Status]` | INT | No | `1` — Object status is delivered: Links as well as for documents module type, checkout and archiving status. +<br>(see <<dms-getresultlist-status,Object Status>>) |
| `[CheckParams]` | INT | No | `0` — Missing parameter values in conditions are ignored (Default). +<br>`1` — Error message if a referenced parameter is not defined. |
| `[AutoStar]` | INT | No | Automatic appending of `*` at text field conditions. +<br>`1` = at beginning, `2` = at end, `3` = at beginning and end. |
| `[QueryLanguage]` | INT | No | Language code for DMS names in the request. Default: `0` (default language). |
| `[QueryCatalogeLocale]` | STRING | No | Locale (e.g. `de_DE`) for multilingual catalog values in the request. +<br>Empty string → technical values are used. |
| `[OutputLanguage]` | INT | No | Language code for DMS names in the result document. Default: `0` (default language). |
| `[OutputCatalogueLocale]` | STRING | No | Locale (e.g. `de_DE`) for multilingual catalog values in the result. +<br>Empty string → technical values are output. |
| `[DisableSearchGroups]` | INT | No | `1` — Search groups are not considered; conditions apply only to the defined field. +<br>`0` — Conditions refer to all fields of a search group (Default). |
| `[JobUserGUID]` | STRING | No | User context for job execution +<br>(see [The JobUserGUID Parameter](reference/xml_import_reference.md)). |
| `[GarbageMode]` | INT | No | `1` — Only objects from the trash can are considered. +<br>`0` — Objects from the trash can are excluded. |
| `[RegisterTree]` | INT | No | `1` — Register tree information (ID and type) is determined as XML. Default: `0`. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Count` | INT | — | Number of returned records. |
| `TotalHits` | INT | — | Total number of available hits. |
| `[FileCount]` | INT | Optional | Number of returned files (always `1`). |
| `[XML]` | BASE64 | If `Flags` ≠ `0x00000010 (16)` | Hit list in XML format as buffer. |

### Output Files

| Name | Description |
|---|---|
| `[File list]` | Path and name of the XML file with the hit list. +<br>Only present when `Flags = 0x00000010 (16)` is set. |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

### Detailed Description

A request essentially consists of defining the requested DMS object,
selecting the fields to be returned, and setting search conditions.
Additionally, location information can be requested, full-text or
base parameter searches performed, links to objects from other cabinets
created, or requests parameterized.

#### Request Types

In search requests, linear and hierarchical requests are generally distinguished.
Detail requests represent a special case.

##### Linear Requests / Linear Object Lists (LOL)

Linear requests can request simple index data of objects of a certain type.
Table controls and multi-parameter fields are excluded from this.

When requesting documents or registers, fields of the direct parent register
and folder can also be requested.

##### Hierarchical Requests / Hierarchical Object Lists (HOL)

Hierarchical requests can not only return the content of table controls and
multi-parameter fields, but also child elements — for example, registers
and documents within the requested folder. Additionally, object properties
such as document variants, access rights and notes can be requested.

In contrast to linear requests, for hierarchical requests at least one
additional database query must be performed for each hit.
Each requested object property increases this number.

##### Mixed Requests (MIX)

Mix of linear and hierarchical request: complex information about folders or
registers combined with simple information about their direct child objects.
One database query is made per child object type.

#### Result Formats

The XML format for request results follows the [DMSContent XML format](xsd/DMSContent.md).
It always starts with the `<DMSContent>` element, which indicates the type (`LOL`, `HOL` or `MIXED`) via the `format` attribute.

##### Linear Object List (LOL)

Linear object lists are initiated by the `<Rowset>` element. They have a
tabular structure with a header (`<Columns>`) and hit rows (`<Rows>`).

##### Hierarchical Object List (HOL)

Hierarchical hit lists are initiated by the `<ObjectList>` element.
For each hit object, field definitions and field values are written.
The `<ChildObjects>` element can represent arbitrary hierarchy depths.

```xml
<ObjectList>
  <ObjectType name="Admission" id="196616" type="REGISTER" table="object12">
    <Object id="3226">
      <Fields>
        <Field name="Case Number" datatype="TEXT" dbname="feld62" ostype="X" size="20">987654</Field>
        <Field name="Start" datatype="DATE" dbname="datum1" ostype="D" size="10">01.10.2003</Field>
        <Field name="End" datatype="DATE" dbname="datum2" ostype="D" size="10"/>
      </Fields>
      <ChildObjects>
        <!-- Document type 'Medical Letter' -->
        <ObjectType name="Medical Letter" id="262273" type="DOCUMENT" modul="WINDOWS" table="object162">
          <ObjectList>
            <Object id="37744">
              <Fields>
                <Field name="Date" datatype="DATE" dbname="datum1" ostype="D" size="10">12.11.2003</Field>
                <Field name="Physician" datatype="TEXT" dbname="feld1" ostype="X" size="50">DEMO</Field>
                <Field name="Type" datatype="TEXT" dbname="feld3" ostype="X" size="20">Surgical Medical Letter</Field>
                <Field name="Status" datatype="INTEGER" dbname="zahl2" ostype="9" size="1"/>
              </Fields>
            </Object>
          </ObjectList>
          <Statistics startpos="0" pagesize="5" total_hits="1"/>
        </ObjectType>
      </ChildObjects>
    </Object>
  </ObjectType>
  <Messages/>
</ObjectList>
```

##### Displaying Field Values

Generally, field values are output as XML element text. For certain field types
(time, timestamp, option buttons, system field Owner, trees, multilingual catalogs)
the database value is output as a `value` attribute and the display text as element text.

Example LOL: `<Value value="M">male</Value>`

Example HOL:
`<Field value="M" name="Gender" datatype="TEXT" dbname="feld7" ostype="X" size="1">male</Field>`

##### The `<Statistics>` Element

At the end of each hit list, the `<Statistics>` element provides information about the result scope:

`<Statistics startpos="20" pagesize="20" total_hits="50"/>`

##### The `<Messages>` Element

Information about faulty requests appears in `<Message>` elements:

```xml
<Messages>
  <Message faultcode="-2116351928" sourcecode="475">
    The full-text search could not be performed because no search text was specified.
  </Message>
</Messages>
```

##### Combination of Request Types and Output Formats

| \| | TXT | LOL | HOL |  |  |  |  |  |  |
|---|---|---|---|---|---|---|---|---|---|
| LOL | ✓ | ✓ | ✓ | MIX | \| ✓ | ✓ | HOL | \| | ✓ |

#### General Request Behavior

In a search request, search conditions can be formulated for one or more object types —
for example, for both registers and folders in a document request.

This behavior is controlled by the `RegisterContext` parameter:

* `1` (Default) — Register conditions are taken into account.
* `0` — Register clauses are ignored; only objects in registers are requested (HOL).

#### Creating Requests

First, the DMS objects and fields to be requested must be defined. Objects and fields can be identified by:

* `name` — speaking OS name
* `internal_name` — internal name
* `osguid` — OSGUID
* `table` / `dbname` — database table or column name

##### Simple Example

Request all folders of the cabinet _Patient_ with all index data.
The `type` attribute (`FOLDER`, `REGISTER`, `DOCUMENT`) avoids name conflicts between
similarly named object types.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSQuery>
  <Archive internal_name="patient">
    <ObjectType internal_name="patient_folder" type="FOLDER">
      <Fields field_schema="ALL"/>
    </ObjectType>
  </Archive>
</DMSQuery>
```

##### Define Fields Explicitly

If not all index data is needed, set `field_schema="DEF"` and list the desired fields individually:

```xml
<Fields field_schema="DEF">
  <Field internal_name="firstname"/>
  <Field internal_name="postal_code_city"/>
  <Field internal_name="city"/>
</Fields>
```

##### System Fields

System fields are requested with the `system="1"` attribute and specified by internal name,
GUID or database field name.
A complete overview of all available system fields is provided in System Fields.

```xml
<Archive internal_name="patient">
  <ObjectType internal_name="images" type="DOCUMENT">
    <Fields field_schema="ALL">
      <Field internal_name="OBJECT_COUNT" system="1"/>
    </Fields>
  </ObjectType>
</Archive>
```

##### Sorting

Sorting via the `sortpos` attribute (priority, value > 0) and `sortorder` (`ASC` / `DESC`).
Fields with lower `sortpos` have higher priority.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSQuery>
  <Archive internal_name="patient">
    <ObjectType internal_name="admission" type="REGISTER">
      <Fields field_schema="ALL">
        <Field internal_name="author" sortpos="1" sortorder="ASC"/>
        <Field internal_name="date" sortpos="2" sortorder="DESC"/>
      </Fields>
    </ObjectType>
  </Archive>
</DMSQuery>
```

#### Search Conditions

Conditions can be formulated for the requested object as well as parent and child objects.
The `<ConditionObject>` attribute determines for which object the conditions apply.

##### Combined Queries Across Multiple Object Types

Conditions can simultaneously reference fields of different object types within the same
cabinet. The server returns only those objects for which all conditions are satisfied —
regardless of which object type a particular condition refers to.

The following combinations are supported:

* Searching for a document with conditions on fields of the document itself, its register,
and its folder.
* Searching for a register or folder that contains a child object matching a specific
condition.

> **Note:** For nested registers, only the immediately superior register is available as a
condition target — its parent registers cannot be referenced.

**Variant 1 — Searching for child objects based on parent object criteria**

Retrieve all body measurements (_body_measurements_) that are stored in an admission
register for the _Cardiology_ ward and where the patient's height exceeds 180 cm.
The requested object is the document; the condition on the register restricts the search
space to admissions in the desired ward.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSQuery>
  <Archive internal_name="patient">
    <ObjectType internal_name="body_measurements" type="DOCUMENT">
      <Fields field_schema="DEF">
        <Field internal_name="body_height_cm"/>
        <Field internal_name="body_weight_kg"/>
      </Fields>
      <Conditions>
        <ConditionObject internal_name="admission" type="REGISTER">
          <FieldCondition internal_name="ward" operator="=">
            <Value>Cardiology</Value>
          </FieldCondition>
        </ConditionObject>
        <ConditionObject internal_name="body_measurements" type="DOCUMENT">
          <FieldCondition internal_name="body_height_cm" operator="&gt;">
            <Value>180</Value>
          </FieldCondition>
        </ConditionObject>
      </Conditions>
    </ObjectType>
  </Archive>
</DMSQuery>
```
**Variant 2 — Searching for parent objects based on child object criteria**

Retrieve all admissions (_admission_) that contain at least one body measurement with a
height greater than 180 cm.
The requested object is the register; the condition references a subordinate document.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSQuery>
  <Archive internal_name="patient">
    <ObjectType internal_name="admission" type="REGISTER">
      <Fields field_schema="DEF">
        <Field internal_name="ward"/>
        <Field internal_name="start_date"/>
      </Fields>
      <Conditions>
        <ConditionObject internal_name="body_measurements" type="DOCUMENT">
          <FieldCondition internal_name="body_height_cm" operator="&gt;">
            <Value>180</Value>
          </FieldCondition>
        </ConditionObject>
      </Conditions>
    </ObjectType>
  </Archive>
</DMSQuery>
```

##### Comparison Operators

| Operator | XML-conforming format |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| `<` | `&lt;` | `<=` | `&lt;=` | `=` | `=` | `!=` | `!=` | `>` | `&gt;` | `>=` | `&gt;=` | `BETWEEN` | `BETWEEN` | `NOT BETWEEN` | `NOT BETWEEN` | `IN` | `IN` | `NOT IN` | `NOT IN` |

##### Wildcards (Text Fields)

| Wildcard | Meaning |  |  |  |  |
|---|---|---|---|---|---|
| `*` | Any character sequence | `?` | Single character | `~` | Phonetic search (only MSSQL and Oracle) |
Escape character: Backslash — `\?` searches for a question mark.
LIKE operator is used automatically if wildcards are present.

##### Null Value

To check for NULL, use `<NULL/>` instead of `<Value>`.

##### Date

Date values can be passed in all common formats.
Two-digit years: xy < 50 → 20xy, xy ≥ 50 → 19xy.

For incomplete date values with the equality operator, search is performed
within the corresponding time range:

* `=1999` → `BETWEEN 1.1.1999 AND 31.12.1999`
* `!= 1999` → `NOT BETWEEN 1.1.1999 AND 31.12.1999`

If two `<Value>` elements are specified, `BETWEEN` is used automatically.

##### Search Conditions for Table Fields

```xml
<DMSQuery>
  <Archive internal_name="test_cabinet">
    <ObjectType internal_name="windoc">
      <Fields field_schema="ALL"/>
      <Conditions>
        <ConditionObject internal_name="windoc">
          <TableCondition name="MyTable">
            <TableColumn name="1.Column" operator="=">
              <Value>11</Value>
            </TableColumn>
          </TableCondition>
        </ConditionObject>
      </Conditions>
    </ObjectType>
  </Archive>
</DMSQuery>
```

##### Boolean Connections (AND / OR)

By default, conditions are connected with AND. For OR connections, field conditions
are grouped under `<FieldGroup operator="OR">`. Nesting is possible.

```xml
<Conditions>
  <ConditionObject internal_name="press_archive">
    <FieldGroup operator="OR">
      <FieldCondition internal_name="subject_area">
        <Value>Technology</Value>
      </FieldCondition>
      <FieldCondition internal_name="created_by">
        <Value>Smith</Value>
      </FieldCondition>
    </FieldGroup>
    <Created>
      <From>1.1.2002</From>
      <To>31.12.2003</To>
    </Created>
  </ConditionObject>
</Conditions>
```
Multiple `<ConditionObject>` elements for the same object type are connected with OR.

##### Base Parameter Search Conditions

| XML Element | Meaning |  |  |  |  |  |  |  |  |  |  |  |  |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| `<Creator>` | Creator | `<Created>` | Creation date | `<Modifier>` | Last modifier | `<Modified>` | Date of last change (two values → range) | `<Owner>` | Username of owner | `<ArchiveState>` / `<ArchiveStateValue>` | Archiving status (documents only): +<br>`ARCHIVED`, `ARCHIVABLE`, `NOT_ARCHIVABLE`, `NO_PAGES`, `PAGE_ERROR`, `REFERENCE` | `<Locked>` / `<LockStateValue>` | Checkout status (documents only): +<br>`UNLOCKED`, `SELF`, `OTHERS`, `EXTERNAL` |

##### OBJECT_SEARCHFLAGS

Base parameter properties of documents as search condition:

```xml
<Conditions>
  <ConditionObject internal_name="document1" type="DOCUMENT">
    <FieldCondition internal_name="OBJECT_SEARCHFLAGS" system="1">
      <Value>68</Value>
    </FieldCondition>
  </ConditionObject>
</Conditions>
```
Values are combined bitwise: Value `68` = `IN_REGISTER` (64) AND `NOT_ARCHIVABLE` (4).

* Values of the same group → logically OR
* Values of different groups → logically AND

| Constant | Hex | Decimal | Description |
|---|---|---|---|
| `ARCHIVED` | `0x0001` | 1 | Document is archived |
| `ARCHIVABLE` | `0x0002` | 2 | Document is released for archiving |
| `NOT_ARCHIVABLE` | `0x0004` | 4 | Document is not released for archiving |
| `WITHOUT_PAGES` | `0x0008` | 8 | Document has no pages |
| `CHECKOUT_BY_ME` | `0x0010` | 16 | Document is checked out by current user |
| `CHECKOUT_BY_OTHER` | `0x0020` | 32 | Document is checked out by another user |
| `IN_REGISTER` | `0x0040` | 64 | Document is in a register |
| `NOT_IN_REGISTER` | `0x0080` | 128 | Document is not in a register (directly on folder level) |
| `EXTERNAL` | `0x0100` | 256 | Document is an external document |
| `LINK` | `0x0200` | 512 | Document is a document link |
| `MULTI_LOCATION` | `0x0400` | 1024 | Document is located at multiple places |
| `HAS_VARIANTS` | `0x0800` | 2048 | Document has variants |
| `SIGNED_CURRENT_VERSION` | `0x1000` | 4096 | Current version of the document is signed |
| `SIGNED_FORMER_VERSION` | `0x2000` | 8192 | A former version of the document is signed |

##### Full-text Conditions

Through `<Fulltext>`, a full-text search is performed. The optional attribute
`query_catalogue_locale` sets the language for multilingual catalogs.

##### Request Parameterization

Parameters are defined below `<DMSQuery>` and referenced in conditions via the
`ref` attribute in the `<ParamValue>` element:

```xml
<DMSQuery>
  <Params>
    <Param name="PatID">3987</Param>
  </Params>
  <Archive internal_name="patient">
    <ObjectType internal_name="patient_folder">
      <Fields field_schema="ALL"/>
      <Conditions>
        <ConditionObject internal_name="patient_folder">
          <FieldCondition internal_name="patient_id">
            <ParamValue ref="PatID"/>
          </FieldCondition>
        </ConditionObject>
      </Conditions>
    </ObjectType>
  </Archive>
</DMSQuery>
```

##### Cross-Cabinet Requests

Via `<ExternalObjects>`, information from another cabinet can be linked in HOL requests.
The linking is done via a `link_name` attribute on the outgoing field and a
`<LinkedValue ref="..."/>` reference in the external object:

```xml
<DMSQuery>
  <Archive internal_name="press_archive">
    <ObjectType internal_name="bw_scans">
      <Fields>
        <Field internal_name="document_type"/>
        <Field internal_name="author" link_name="author"/>
        <Field internal_name="date"/>
      </Fields>
      <ExternalObjects>
        <ExternalArchive internal_name="addresses">
          <ExternalObjectType internal_name="addresses">
            <Fields field_schema="ALL"/>
            <SubConditions>
              <FieldCondition internal_name="last_name">
                <LinkedValue ref="author"/>
              </FieldCondition>
            </SubConditions>
          </ExternalObjectType>
        </ExternalArchive>
      </ExternalObjects>
    </ObjectType>
  </Archive>
</DMSQuery>
```

##### Location Information

`<ParentObjects>` is an **HOL-exclusive** element. It delivers the complete object path
(folder, register) to the hit object.

In LOL requests, parent fields are not available via `<ParentObjects>` —
fields of the direct parent register and folder can be included directly in the `<Fields>` list
and appear in the hit row.

`<ParentObjects>` supports the attributes:

* `parent_schema` — which parent types are returned; default: `DEF` +
  Valid values: [object_schema](xsd/DMSQuery.md) (`DEF`, `ALL`, `REGISTER`, `DOCUMENTS`)
* `field_schema` — standard field selection for all parent objects +
  Valid values: [field_schema](xsd/DMSQuery.md) (`DEF`, `ALL`, `ALLREL`, `MIN`)

Child elements:

* `<ParentObjectType>` — one or more explicitly desired parent types
* `<SubObjectType>` — the requested target object in the path (type and internal name)

```xml
<DMSQuery requesttype="HOL">
  <Archive internal_name="patient">
    <ObjectType internal_name="medical_letter" type="DOCUMENT">
      <Fields field_schema="DEF">
        <Field internal_name="date"/>
        <Field internal_name="physician"/>
      </Fields>
      <ParentObjects parent_schema="DEF">
        <SubObjectType internal_name="medical_letter" type="DOCUMENT"/>
      </ParentObjects>
    </ObjectType>
  </Archive>
</DMSQuery>
```

##### Exporting Hierarchical Structures (HOL)

`<ChildObjects>` is an **HOL-exclusive** element. It determines which child objects
are delivered hierarchically.

Attributes:

* `child_schema` — which child types are returned; default: `DEF` +
  Valid values: [object_schema](xsd/DMSQuery.md) (`DEF`, `ALL`, `REGISTER`, `DOCUMENTS`)
* `export_depth` — depth of hierarchy (`0` = direct children, `1` = children and grandchildren etc.); default: `0`
* `field_schema` — standard field selection for all child types +
  Valid values: [field_schema](xsd/DMSQuery.md) (`DEF`, `ALL`, `ALLREL`, `MIN`)

Child elements of `<ChildObjects>`:

* `<ChildObjectType>` — one element per requested child type; carries the same identification attributes as `<ObjectType>` plus:
** `alias` — alias name for similarly named types in the hit list
** `<Fields>` — desired fields of the child type
** `<SubConditions>` — additional filter conditions for child objects
** `<ExternalObjects>` — linked foreign archive objects of the children

```xml
<DMSQuery requesttype="HOL">
  <Archive internal_name="patient">
    <ObjectType internal_name="admission" type="REGISTER">
      <Fields field_schema="DEF">
        <Field internal_name="case_number"/>
        <Field internal_name="admission_date"/>
      </Fields>
      <ChildObjects child_schema="DEF" export_depth="0">
        <ChildObjectType internal_name="medical_letter" type="DOCUMENT">
          <Fields field_schema="DEF">
            <Field internal_name="date"/>
            <Field internal_name="physician"/>
          </Fields>
        </ChildObjectType>
      </ChildObjects>
    </ObjectType>
  </Archive>
</DMSQuery>
```

##### Full-text Searches

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSQuery>
  <Archive internal_name="patient">
    <FulltextQuery>
      <ChildObjects child_schema="DEF">
        <ChildObjectType internal_name="medical_letter">
          <Fields>
            <Field internal_name="date"/>
            <Field internal_name="senior_physician"/>
            <Field internal_name="type"/>
          </Fields>
        </ChildObjectType>
        <ChildObjectType internal_name="diagnosis">
          <Fields field_schema="ALL"/>
        </ChildObjectType>
      </ChildObjects>
      <Fulltext>Meningitis</Fulltext>
    </FulltextQuery>
  </Archive>
</DMSQuery>
```

##### Multiple Requests in One Document

```xml
<DMSQuery>
  <Archive internal_name="addresses">
    <ObjectType internal_name="addresses">
      ...
    </ObjectType>
  </Archive>
  <Archive internal_name="patient">
    <ObjectType internal_name="color_images" alias="F2">...</ObjectType>
    <ObjectType internal_name="grayscale_images" alias="G1">...</ObjectType>
    <ObjectType internal_name="color_images" alias="F1">...</ObjectType>
  </Archive>
</DMSQuery>
```
The optional `alias` attribute in the `<ObjectType>` element enables targeted access to
results of similarly named object types in the hit list.

#### Paging Through Hit Lists

With `PageSize` (page size), `Offset` (start position) and `MaxHits` (hit upper limit),
hit lists can be retrieved page by page. The `<Statistics>` element at the end of each
hit list provides information about the scope:

`<Statistics startpos="20" pagesize="20" total_hits="50"/>`

Example: PageSize=20, MaxHits=101, actually 120 hits:

| Page | Input | `<Statistics>` output |  |  |  |  |  |  |  |  |  |  |  |  |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | `Offset=0` | `startpos='0'  pagesize='20' total_hits='101'` | 2 | `Offset=20` | `startpos='20' pagesize='20' total_hits='101'` | 3 | `Offset=40` | `startpos='40' pagesize='20' total_hits='101'` | 4 | `Offset=60` | `startpos='60' pagesize='20' total_hits='101'` | 5 | `Offset=80` | `startpos='80' pagesize='20' total_hits='101'` |
After page 1: (101-1) / 20 = 5 pages. Since `total_hits=101 > MaxHits-1=100`,
there are further hits beyond the upper limit.

#### Base Parameters

With `baseparams=1`, in addition to index data, all base parameters are delivered.
In HOL they appear in a separate `<BaseParams>` group:

For all object types: creator, creation date, modifier, modification date, owner
(name as text, GUID as `osguid` attribute).

For documents additionally: check-in/check-out status, archiving status, retention periods.

```xml
<BaseParams>
  <Creator>love</Creator>
  <Created>12.12.2003</Created>
  <Modifier>root</Modifier>
  <Modified>14.12.2003</Modified>
  <Owner guid="BC1123CDFAAAS">love</Owner>
  <ArchiveState>ARCHIVABLE</ArchiveState>
  <Locked>SELF</Locked>
</BaseParams>
```

#### Object Status

With `status=1` in the `<DMSQuery>` element, the following status information is determined for each object:

* Links

For documents additionally:

* Module type
* Archiving status
* Checked in / Checked out
* Number of pages
* Number of real document pages (system field [OBJECT_DOCPAGECOUNT](reference/dms_reference.md))

#### Rights

With `rights=1` in the `<DMSQuery>` element, the access rights of the requesting
user are determined for each object:

| Attribute | Description |  |  |  |  |  |  |
|---|---|---|---|---|---|---|---|
| `modify_index` | User may change index data | `delete_object` | User may delete the object | `export_object` | User may open or export the object | `modify_object` | User may edit the object |
Example: `<Rights modify_index="1" delete_object="1" export_object="1" modify_object="1"/>`

With `ObjectInserts=1`, the insertable instances for each possible child object type are determined:

```xml
<Rights object_inserts="1" modify_index="1" delete_object="1" export_object="1" modify_object="1">
  <ObjectInserts type="65536" count="-1"/>
  <ObjectInserts type="131108" count="-1"/>
  <ObjectInserts type="131119" count="0"/>
  <ObjectInserts type="196608" count="-1"/>
  <ObjectInserts type="262144" count="-1"/>
</Rights>
```
`count="-1"` means no restriction. If `rights=1` was not set, all
right attributes are set to `-1`.

#### File Information

With `fileinfo=1`, for each document the following properties are written as attributes in `<FileProperties>`:

| Attribute | Description |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| `count` | Number of files | `size` | Document size in bytes | `extension` | File type standard extension | `mimetype` | MIME type | `mimetypegroup` | MIME type group (e.g. `image`, `document`) | `linkid` | ID of the linked object (if `FollowDocLink=1`) | `linktypeid` | Type ID of the linked object (if `FollowDocLink=1`) | `documentpagecount` | Number of document pages (if known) |
> **Note:** The attributes `extension`, `mimetype` and `mimetypegroup` are not available for LOL queries and are only returned for HOL queries.

Example: `<FileProperties count="1" size="179489" extension="jpg" mimetype="image/jpeg"/>`

#### Notes

With the `<DMSQuery>` attribute `remarks="1"`, notes and note links
are returned for each requested document (HOL only):

| Attribute / Element | Description |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| `id` | ID of the note | `type` | Note type: `1`=White, `2`=Yellow, `3`=Green, `4`=Blue | `relation` | `1` for object relation | `medium` | Medium ID (work directory) or `0` (database) | `<Creator>` | Creator name (ID as attribute) | `<Created>` | Creation date (timestamp as attribute) | `<Modifier>` | Last modifier (ID as attribute) | `<Modified>` | Date of last modification (timestamp as attribute) | `<Text>` | Note text (ID as attribute; empty for object note) |
```xml
<Object id="81">
  <Remarks>
    <Remark id="1413" type="1" relation="0" medium="4">
      <Creator id="16">SMITH</Creator>
      <Created value="1143560855">28.03.2006 17:47:35</Created>
      <Modifier id="18">JONES</Modifier>
      <Modified value="1946463756">30.04.2006 14:50:12</Modified>
      <Text>Note text</Text>
    </Remark>
  </Remarks>
</Object>
```

#### Language Settings

Through `lang_id` or `query_language`, the language for field and object names in the
request can be set.

For multilingual catalogs, `QueryCatalogueLocale` (job parameter),
`query_catalogue_locale` (XML attribute at root or field) is available.
The field-specific locale overrides the global setting.

> **Note:** A multilingual catalog cannot be requested with different
locales within a single request.

#### Icons

With `icons="1"` in the `<DMSQuery>` element, icon IDs of all custom icons
are returned. The `iconid` attribute is attached to `<Object>` (HOL only; `icons="1"` is ignored for LOL queries).

Image files for an icon ID can be retrieved via [`cnv.GetIcons`](cnv.md#cnv.GetIcons).

#### Document Variants

With `variants="1"` in the `<DMSQuery>` element, for W-documents the variant tree
is output via `<DocumentVariant>` and `<DocumentVariants>` elements
(without index data).

| Attribute | Meaning |  |  |  |  |  |  |
|---|---|---|---|---|---|---|---|
| `is_active` | `1` = active variant | `doc_id` | Document ID of this variant | `doc_ver` | Version identifier | `doc_parent` | ID of the original variant (may also contain ID of deleted documents) |
> **Note:** For searches of W-documents, always the active variant is returned.

### Related Jobs

* [dms.GetObjectDetails](dms.md#dms.GetObjectDetails) — Returns index data of a single object; uses the same [DMSContent HOL format](xsd/DMSContent.md) and same output parameters
* [dms.GetDeletedObjects](dms.md#dms.GetDeletedObjects) — Search for deleted objects with identical DMSQuery format
* [dms.ConvertQuery](dms.md#dms.ConvertQuery) — Converts a DMSQuery between different identifier formats (Name, internal name, GUID, DB-name)
* [dms.AddStoredQuery](dms.md#dms.AddStoredQuery) — Create stored search request
* [dms.GetStoredQuery](dms.md#dms.GetStoredQuery) — Retrieve stored search request
* [dms.ExecuteStoredQuery](dms.md#dms.ExecuteStoredQuery) — Execute stored search request
* [dms.UpdateStoredQuery](dms.md#dms.UpdateStoredQuery) — Update stored search request
* [dms.RemoveStoredQuery](dms.md#dms.RemoveStoredQuery) — Delete stored search request

<a id="dms.GetRevisits"></a>

## dms.GetRevisits

This job returns the open or completed revisits of the current user as an XML list.

====
This job is not described in the official enaio® documentation but is listed as known in the DMS engine overview's "Undocumented Endpoints" section. This description was reconstructed from the call code of the `enaio-jobs-custom` template. On the server, the job prefix is uppercase (`DMS.GetRevisits`); enaio® servers accept both spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Bitfield controlling the response. The call code uses the default `4112` (`0x1010`). |
| `RequestType` | STRING | Yes | Filter by revisit status: `HOL` (open) or analogous server-side codes for completed/rejected entries. Call-code default: `HOL`. |
| `MaxHits` | INT | Yes | Maximum number of returned entries. Call-code default: `1000`. |
| `StartTime` | STRING \\| INT | Yes | Lower bound of the entry timestamp (Unix epoch); `"0"` means "from the beginning". |
| `[FieldSchema]` | STRING | No | Optional schema selector token for the returned index fields. |
| `[XML]` | BASE64 | No | Deprecated; previously used to pass a filter definition, no longer set in the current call code. |

### Output Files

| Name | Description |
|---|---|
| `JobResponseFile` | List of revisits as a UTF-8-encoded XML stream. |

### Return Value

`(INT)`: `0` = job successful, otherwise error code.

For further return values see [Error Codes](errorcodes.md).

### See Also

* [abn.AddRevisit](abn.md#abn.AddRevisit) — adds a revisit
* [abn.SetObjRevisitOpen](abn.md#abn.SetObjRevisitOpen) / [abn.SetObjRevisitClosed](abn.md#abn.SetObjRevisitClosed) — status changes
* [abn.GetUnreadRevisitCount](abn.md#abn.GetUnreadRevisitCount) — number of open revisits
* [dms.GetSubscriptions](dms.md#dms.GetSubscriptions) — analogous counterpart for subscriptions

<a id="dms.GetShadowData"></a>

## dms.GetShadowData

This job allows reading the index data of an object from the shadow tables.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags must be `0` |
| `Guid` | STRING | Yes | GUID of the change operation from the history table (see [dms.GetObjectHistory](dms.md#dms.GetObjectHistory)) |
| `[ObjectID]` | INT | No | ID of the object |
| `[Encoding]` | STRING | No | XML encoding for the result. Allowed are `UTF-16` (Default) and `UTF-8`. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `ShadowData` | BASE64 | — | Index data in [DMSContent](xsd/DMSContent.md) HOL format |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.GetStoredQuery"></a>

## dms.GetStoredQuery

This job returns stored queries in DMS query format. All object fields are included in the list of requested fields. The same output options apply as for [dms.GetResultList](dms.md#dms.GetResultList).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags must be 0 |
| `QueryID` | INT | Yes | ID of the query |
| `[QueryMode]` | INT | No | Sets the desired query behavior. Possible values are: Auto (-1) = Automatically use what is set in the query. Folder (0) = Folders are queried. Cabinet (1) = Cabinets are queried. Document (2) = Documents are queried. Unfiltered (-2) = Folders+Cabinets+Documents are returned. Default is "Unfiltered (-2)". |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `[Query]` | BASE64 | Optional | Query in [DMSQuery](xsd/DMSQuery.md) XML format (UTF-8 encoded) |
| `[ExpertMode]` | INT | Optional | 1, if the stored query is an expert query. |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Stored query:**

```ini
[196608@0]
#OSACT#=1
#OSPOS001#=$STAT1$
[SYSTEM]
NAME=Stat1
IDENT=73706
VARREQUEST=1
DEFACTION=0
```
Converted query:
```xml
<DMSQuery requesttype="LOL" outputformat="LOL">
  <Params>
    <Param name="$STAT1$"/>
  </Params>
  <Archive internal_name="press_archive">
    <ObjectType internal_name="color_images" alias="Stat1">
      <Fields>
        <Field internal_name="date" system="0"/>
        <Field internal_name="author" system="0"/>
        <Field internal_name="source" system="0"/>
        <Field internal_name="content" system="0"/>
        <Field internal_name="viewable" system="0"/>
      </Fields>
      <Conditions>
        <ConditionObject internal_name="color_images">
          <FieldCondition internal_name="author" operator="="
            <ParamValue ref="$STAT1$"/>
          </FieldCondition>
        </ConditionObject>
      </Conditions>
    </ObjectType>
  </Archive>
</DMSQuery>
```

<a id="dms.GetSubscriptions"></a>

## dms.GetSubscriptions

This job returns the active subscriptions of the current user as an XML list — the DMS counterpart to the subscription functions of the `abn` engine.

====
This job is not described in the official enaio® documentation but is listed as known in the DMS engine overview's "Undocumented Endpoints" section. This description was reconstructed from the call code of the `enaio-jobs-custom` template. On the server, the job prefix is uppercase (`DMS.GetSubscriptions`); enaio® servers accept both spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Bitfield controlling the response. The call code uses the default `4112` (`0x1010`). |
| `RequestType` | STRING | Yes | Filter by subscription status (e.g. `HOL` for active subscriptions). Call-code default: `HOL`. |
| `MaxHits` | INT | Yes | Maximum number of returned entries. Call-code default: `1000`. |

### Output Files

| Name | Description |
|---|---|
| `JobResponseFile` | List of subscriptions as a UTF-8-encoded XML stream. |

### Return Value

`(INT)`: `0` = job successful, otherwise error code.

For further return values see [Error Codes](errorcodes.md).

### See Also

* [abn.SetOsInformed](abn.md#abn.SetOsInformed) / [abn.ResetOsInformed](abn.md#abn.ResetOsInformed) — informed markers
* [abn.GetUnreadAboCount](abn.md#abn.GetUnreadAboCount) — number of unread subscription entries
* [dms.GetRevisits](dms.md#dms.GetRevisits) — analogous counterpart for revisits

<a id="dms.GetUserData"></a>

## dms.GetUserData

This job reads user-related data for the specified name and type from the database.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `Type` | INT | Yes | see data types |
| `Name` | STRING | Yes | Identifier for the record |
| `OutputUnicode` | INT | Yes | If set to 1, the name of the return parameter 'sValue' is a string if the data was stored as a string |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `IsUserData` | INT | — | 1 = if the requested entry exists, otherwise 0 |
| `Value` | BASE64 | — | requested value |
| `sValue` | STRING | — | see Input Parameter 'OutputUnicode=1' |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

### See Also

[dms.GetUserDataAsString](dms.md#dms.GetUserDataAsString) +
[dms.GetUserDataNames](dms.md#dms.GetUserDataNames) +
[dms.SetUserData](dms.md#dms.SetUserData) +
[dms.DeleteUserData](dms.md#dms.DeleteUserData)

<a id="dms.GetUserDataAsString"></a>

## dms.GetUserDataAsString

This job reads user-related data for the specified name and type from the database, provided that it is stored as strings. If the data is stored as strings, this job must be used exclusively. The input parameters are identical to [dms.GetUserData](dms.md#dms.GetUserData), except that the output parameter `Value` is returned as a string.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported, must be `0` |
| `Type` | INT | Yes | Data type (see data types) |
| `Name` | STRING | Yes | Identifier for the record |
| `OutputUnicode` | INT | Yes | Must be `1` |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `IsUserData` | INT | — | `1` = if the requested entry exists, otherwise `0` |
| `Value` | STRING | — | requested value as string |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

### See Also

[dms.GetUserData](dms.md#dms.GetUserData)

<a id="dms.GetUserDataNames"></a>

## dms.GetUserDataNames

This job lists the names of all entries for the given type for the logged-in user.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `Type` | INT | Yes | see data types |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Name[1..n]` | STRING | — | Name of the nth entry |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

### See Also

[dms.GetUserData](dms.md#dms.GetUserData)

<a id="dms.GetUserTrayObjects"></a>

## dms.GetUserTrayObjects

This job returns both typed and typeless objects from the logged-in user's tray. The result is returned in DMS Content format. The same output format options apply as for the job [dms.GetResultList](dms.md#dms.GetResultList).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags to control the output format +<br>`0x00000010 (16) = XML result is returned as a file, otherwise as buffer` |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `TotalHits` | INT | — | Number of objects in the user tray |
| `[Result]` | BASE64 | Optional | Object list in [DMSContent](xsd/DMSContent.md) XML format (when Flags is not `0x00000010 (16)`) |

### Output Files

| Name | Description |
|---|---|
| `[FileCount]` | only one file is always returned |
| `[FileList]` | Name and path of the [DMSContent](xsd/DMSContent.md) XML file containing the hit list |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**For output (HOL format):**

```xml
<DMSContent format="HOL" version="4.60.617.4328" timestamp="2004-12-03T14:25:01" user="LIEBE" station="MLIEBE">
  <Archive name="Pressearchiv" id="1" osguid="8EE74447EFC7430F8793F2939A9C044F">
    <ObjectType name="Word-Texte" id="262144" maintype="4" cotype="0" osguid="838360EF620443EF9A66A280CF52F4AE" type="DOCUMENT" modul="WINDOWS" table="object2">
      <ObjectList>
        <Object id="73145">
          <Fields>
            <Field name="links" system="1" datatype="INTEGER" dbname="links" ostype="9" osguid="1114" size="10"> 0 </Field>
            <Field name="anzahl" system="1" datatype="INTEGER" dbname="anzahl" ostype="9" osguid="1101" size="10">1</Field>
            <Field value="2" name="flags" system="1" datatype="INTEGER" dbname="flags" ostype="9" osguid="1102" size="10"> NOT_ARCHIVABLE </Field>
            <Field value="0" name="lockuser" system="1" datatype="INTEGER" dbname="lockuser" ostype="9" osguid="1116" size="10"> UNLOCKED </Field>
            <Field value="4" name="haupttyp" system="1" datatype="INTEGER" dbname="haupttyp" ostype="9" osguid="1108" size="10"> WINDOWS </Field>
            <Field name="Autor" datatype="TEXT" dbname="feld1" ostype="X" osguid="F60B3D9B9E9C4FE8AE6CB78E4DE25826" size="50"> Liebe </Field>
            <Field name="Quelle" datatype="TEXT" dbname="feld2" ostype="X" osguid="E3EDAF50F4F4404C860E6043D7894272" size="150"> Quelle1 </Field>
            <Field value="4711" name="Text2" datatype="TEXT" dbname="feld3" ostype="X" osguid="18C0D7D305DE40BB87A160B1115FC2A3" size="50"> Dokumententext </Field>
          </Fields>
        </Object>
      </ObjectList>
      <Statistics startpos="0" pagesize="-1" total_hits="1"/>
    </ObjectType>
  </Archive>
  <TypelessObjects>
    <TypelessObject id="61359" maintype="2" module="BLACKWHITE" user="LIEBE" timestamp="18.10.2002 11:19:10" pagecount="1"/>
    <TypelessObject id="61360" maintype="2" module="BLACKWHITE" user="LIEBE" timestamp="18.10.2002 11:19:12" pagecount="10"/>
    <TypelessObject id="63399" maintype="3" module="COLOR" user="LIEBE" timestamp="21.01.2003 15:23:36" pagecount="1"/>
  </TypelessObjects>
  <Messages/>
</DMSContent>
```

<a id="dms.GetWorkflowObjects"></a>

## dms.GetWorkflowObjects

This job returns both typed and typeless objects from the workflow archive of the logged-in
user. The result is returned in the DMS Content format. The same
output format options apply as for the job [dms.GetResultList](dms.md#dms.GetResultList).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags for controlling the output format +<br>`0x00000010 (16) = XML result is returned as a file, otherwise as a buffer` |
| `ID<1..n>` | INT | Yes | Object IDs. For each object instance, a separate parameter must be specified. For example ID1=123 ID2=245 … |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `TotalHits` | INT | — | Number of objects actually found in the workflow archive |
| `[Result]` | BASE64 | Optional | Object list in [DMSContent](xsd/DMSContent.md) XML format (when Flags is not `0x00000010 (16)`) |

### Output Files

| Name | Description |
|---|---|
| `[FileCount]` | Only one file is always returned |
| `[File List]` | Name and path of the [DMSContent](xsd/DMSContent.md) XML file containing the hit list |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.GetXMLJobOptions"></a>

## dms.GetXMLJobOptions

This job returns all options of the jobs XMLInsert, XMLUpdate, XMLMove and XMLDelete.

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `JobOptions` | BASE64 | — | List of all job options in XML format |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

> **Note:** More detailed description of `JobOptions`: +
`optionstring` — Name of the option +
`description` — Description of the option +
`defaultvalue` — default value: `SET` (enabled by default), `NOT_SET` (not enabled), `UNDEFINED` (not defined)

**Architecture of JobOptions:**

```xml
<DMSOptions>
  <DMSOption optionstring="..." description="..." defaultvalue="..."/>
  ...
</DMSOptions>
```

### See Also

[Parameter Options](reference/xml_import_reference.md) (for [dms.XMLInsert](dms.md#dms.XMLInsert), [dms.XMLUpdate](dms.md#dms.XMLUpdate), [dms.XMLMove](dms.md#dms.XMLMove), [dms.XMLDelete](dms.md#dms.XMLDelete))

<a id="dms.GetXMLSchema"></a>

## dms.GetXMLSchema

This job returns the specified XML schema as a file.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | must be 0 |
| `Schema` | STRING | Yes | Name of the schema +<br>DMSData = Schema for import +<br>DMSQuery = Schema for DMS queries +<br>DMSContent = Schema for DMS results +<br>DMSAccess = Schema for SSOL jobs +<br>DMSObjDef = Schema for object definitions +<br>Portfolio = Schema for portfolios (folders) |

### Output Files

| Name | Description |
|---|---|
| `File List` | Contains path and name of the XSD file |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.IsUserData"></a>

## dms.IsUserData

This job checks whether an entry already exists for the specified name and type. By default, existence is only checked for the user. If the check should be user-independent – that is, only for the type – the corresponding flag must be set.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | 1 = the existence of the entry is checked independently of the user, otherwise 0 |
| `Type` | INT | Yes | see data types |
| `Name` | STRING | Yes | Identifier for the record |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `IsUserData` | INT | — | 1 = if the requested entry exists, otherwise 0 |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.ModPortfolio"></a>

## dms.ModPortfolio

This job adds objects to an existing portfolio or deletes all objects in the portfolio. If the portfolio is restricted to an object type and it is attempted to add objects of a different object type, this will result in an error.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `Mode` | INT | Yes | 1 = all objects contained in the portfolio are deleted, otherwise 0 |
| `PortfolioXML` | BASE64 | Yes | Description of the portfolio in XML format |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Architecture of PortfolioXML (Description: see Portfolio XML Format)**

```xml
<Portfolio>
  <Objects>
    <Object>
</Object>
  </Objects>
</Portfolio>
```

<a id="dms.ReadSD"></a>

## dms.ReadSD

This job returns the ACEs for a user or user group or all users or user groups for a given object in XML format.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | 0 = Object's ACL is returned; 1 = ACE for user/user group is returned. (see parameter 'Osuid') |
| `ObjectId` | INT | Yes | ID of the object instance |
| `ObjectType` | INT | Yes | Type of the object |
| `[Osuid]` | STRING | No | User or group GUID |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `XmlInfo` | BASE64 | — | ACL in XML format |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Architecture of XmlInfo (Description: see DMSAccess)**

```xml
<DMSAccess>
  <ACL ossd="XXX1">
    <UserACE osuid="YYY1" modify_object="1" export_object="1"/>
    <UserACE osuid="YYY2" modify_object="2" export_object="1"/>
    <GroupACE osuid="YYY3" export_object="1"/>
  </ACL>
</DMSAccess>
```

<a id="dms.RemoveFromPortfolio"></a>

## dms.RemoveFromPortfolio

This job deletes objects in the portfolio.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `PortfolioXML` | BASE64 | Yes | Description of the portfolio in XML format |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Architecture of PortfolioXML (Description: see Portfolio XML Format)**

```xml
<Portfolio>
  <Objects>
    <Object>
</Object>
  </Objects>
</Portfolio>
```

<a id="dms.RemoveStoredQuery"></a>

## dms.RemoveStoredQuery

This job allows deleting an existing stored query.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags must be 0 |
| `QueryID` | INT | Yes | ID of the query |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

No job-specific return values.

<a id="dms.RestoreIndexdataVersion"></a>

## dms.RestoreIndexdataVersion

This job restores a specified version from the index data history.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported |
| `ObjectID` | INT | Yes | ID of the document whose index data should be restored |
| `Guid` | STRING | Yes | GUID of the version of the object to be restored |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

No job-specific return values.

<a id="dms.RetrievePortfolios"></a>

## dms.RetrievePortfolios

This job returns all portfolios that match the specified search criteria.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `Created_to` | Long | Yes | Timestamp until which the portfolio was created. 0=Unrestricted |
| `PortfolioXML` | BASE64 | Yes | Search criteria for portfolio in XML format |
| `[GarbageMode]` | INT | No | `1` = Only consider objects from the trash. `0` = Do not consider objects from the trash (Default). |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `PortfoliosXML` | BASE64 | — | List of all found portfolios in XML format |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Architecture of PortfolioXML (Description: see Portfolio XML Format)**

```xml
<Portfolio>
</Portfolio>
```

<a id="dms.SelectDistinctFieldValues"></a>

## dms.SelectDistinctFieldValues

This job returns a list of all values of a given DMS field. Multiple parameter fields cannot be considered.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `[FieldName]` | STRING | No | Name of the field |
| `[ColumnName]` | STRING | No | When [FieldName] refers to a table, [ColumnName] must specify the column. Access rights are not checked, [Filter] is not possible. |
| `[Notation]` | INT | No | Type of field name: 0 (Default) = DMS Name, 1 = internal name, 2 = database field name |
| `[Filter]` | STRING | No | Restriction/Search criterion. For text fields, a * is automatically appended. For tables, [Filter] is not evaluated. |
| `[SortOrder]` | STRING | No | Sort order. Allowed values: 'ASC' (default) or 'DESC' |
| `[MaxHits]` | INT | No | Maximum number of values to return. Default=-1 (all) |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `Count` | INT | — | Number of output field values (see input parameter Max Hits) |
| `FieldValues` | BASE64 | — | Object list in UTF-8 encoded DMSFieldValueList XML format: |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.SetSD"></a>

## dms.SetSD

This job creates one or more access control entries.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Currently not supported -> pass 0 |
| `XmlInfo` | BASE64 | Yes | XML-formatted string containing the ACEs |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

**Architecture of XmlInfo (Description: see DMSAccess)**

```xml
<DMSAccess>
  <ACL ossd="XXX1">
    <UserACE osuid="YYY1" modify_object="1" export_object="1"/>
  </ACL>
  <ACL ossd="XXX2">
    <UserACE osuid="YYY1" modify_object="1" export_object="1"/>
    <UserACE osuid="YYY2" modify_object="2" export_object="1"/>
  </ACL>
  <ACL ossd="XXX3">
    <GroupACE osuid="YYY3" export_object="1"/>
  </ACL>
</DMSAccess>
```

<a id="dms.SetUserData"></a>

## dms.SetUserData

This job stores user-related data in the database. If no entry exists yet for the specified name and type, a new entry is created. The check whether an entry already exists can be performed using the job [dms.IsUserData](dms.md#dms.IsUserData)

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | reserved, must be 0 |
| `Type` | INT | Yes | see data types |
| `Name` | STRING | Yes | Identifier for the record |
| `Value` | BASE64 | Yes | Value to be stored |
| `sValue` | STRING | Yes | Value to be stored in string format (See comment below) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.SetUserDataAsString"></a>

## dms.SetUserDataAsString

This job writes user-related data for the specified name and type to the database,
provided that these must be stored as strings. If these must be stored as strings, only
this job must be used. The input parameters correspond to [dms.SetUserData](dms.md#dms.SetUserData),
only `Value` (BASE64) is replaced by `sValue` (STRING).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | reserved, must be `0` |
| `Type` | INT | Yes | Data type (see data types) |
| `Name` | STRING | Yes | Identifier for the data record |
| `sValue` | STRING | Yes | Value to be stored as string |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

### See Also

[dms.SetUserData](dms.md#dms.SetUserData)

<a id="dms.UndoCheckOutDocument"></a>

## dms.UndoCheckOutDocument

This job undoes the checkout of the specified document.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | 1 = the checkout can be undone from another station, otherwise 0 |
| `ArchiveType` | INT | Yes | Type of the cabinet |
| `ObjectID` | INT | Yes | ID of the document |
| `ObjectType` | INT | Yes | Type of the object |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `[Info]` | STRING | Optional | If another user attempts to undo the checkout, the name of the checker-out will be returned (same applies for the station) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

* `-1037` — The document has been checked in.

<a id="dms.UpdateOsEvent"></a>

## dms.UpdateOsEvent

Updates the script code of an existing OS event.

====
This job accesses the internal scripting infrastructure of enaio® directly. Incorrectly configured events can cause unexpected behavior or serious malfunctions on the client or server side.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `OsEventId` | INT | Yes | ID of the event to update. Corresponds to the `id` field in the JSON response of [dms.GetOsEvents](dms.md#dms.GetOsEvents). |
| `VBCode` | STRING | Yes | New script code of the event (JavaScript or VBScript). +<br>Description: Field `vb_code` |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

<a id="dms.UpdatePDFAnnotations"></a>

## dms.UpdatePDFAnnotations

This job modifies one or more existing PDF annotations on a DMS object.
The annotations to update are passed as a JSON document.

====
This job is not listed in the official enaio® DMS engine overview. This description was reconstructed from the call code of the `enaio-jobs-custom` template. On the server, the job prefix is uppercase (`DMS.UpdatePDFAnnotations`); enaio® servers accept both spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Reserved; always pass `0`. |
| `JSON` | BASE64 | Yes | Annotations to update, in JSON format (including their IDs). |
| `OutputUnicode` | INT | Yes | `1` = response as Unicode strings; `0` = legacy bytearray encoding. |

### Return Value

`(INT)`: `0` = job successful, otherwise error code. No content output parameters are returned.

For further return values see [Error Codes](errorcodes.md).

### Required Roles

The caller needs the following [system roles](mng.md):

* `81` — Client: View preview annotations
* `82` — Client: Edit preview annotations

### See Also

* [dms.CreatePDFAnnotations](dms.md#dms.CreatePDFAnnotations) — adds new annotations
* [dms.GetPDFAnnotations](dms.md#dms.GetPDFAnnotations) — reads annotations
* [dms.DeletePDFAnnotations](dms.md#dms.DeletePDFAnnotations) — deletes annotations

<a id="dms.UpdateStoredQuery"></a>

## dms.UpdateStoredQuery

This job allows updating an existing stored query and/or its properties. The query must be passed in DMS query format. The query is converted to the internal format for stored queries. Since the format for stored queries only allows a subset of DMS query possibilities, there are certain limitations. See [dms.ConvertQuery](dms.md#dms.ConvertQuery).

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Flags must be 0 |
| `QueryID` | INT | Yes | ID of the query |
| `[Query]` | BASE64 | No | Query in [DMSQuery](xsd/DMSQuery.md) XML format |
| `[Name]` | STRING | No | New name of the query, if the query should be renamed |
| `[IconID]` | INT | No | ID of an icon that is displayed in the client. Default=0 |
| `[DefAction]` | INT | No | Action to be performed when opening the stored query. +<br>`0` = Execute (Default), `1` = Edit, `2` = Count |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

No job-specific return values.

<a id="dms.WriteShadowData"></a>

## dms.WriteShadowData

This job writes shadow data (a shadow copy of selected index field values) for a DMS
object. Shadow data is persisted separately from the main object and is used in particular:

* as a snapshot before structural changes on the main object (audit / backup),
* as a writable index copy when the original object is read-only due to
retention / archiving,
* as supply data for a secondary archive (e.g. a long-term archive) that needs to retain
the index values without writing back into the main archive.

The data can subsequently be read back through [dms.GetShadowData](dms.md#dms.GetShadowData).

====
This job is not listed in the official enaio® DMS engine overview.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ObjectID` | INT | Yes | Numeric ID of the DMS object. |
| `ObjectType` | INT | Yes | Object type ID of the DMS object (see Object type ID). |
| `ArchiveType` | INT | Yes | Target archive / type identifier for the shadow storage. Typically correlates with the<br>main type of the object; differing values are possible when the shadow data is to be<br>written into a different archive. |
| `UserIdent` | INT | Yes | Numeric user ID of the triggering user (for the audit trail and permission check). |
| `Flags` | INT | Yes | Reserved; always pass `0`. |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `GUID` | STRING | — | GUID of the newly created shadow entry. Empty (`''`) when no new entry was created —<br>either because an existing entry was updated, or because no shadow data is configured for<br>this object type / archive. `return_code = 0` signals success in either case. |

### Return Value

`(INT)`: `0` = job successful, otherwise error code (e.g. object does not exist, invalid
`ArchiveType`, database error).

For further return values see [Error Codes](errorcodes.md).

### Notes

* Idempotent — repeated calls with identical parameters typically result in an UPDATE of
the existing shadow entry rather than an additional INSERT.
* An empty `GUID` output is not an error (see parameter description).

### Related Jobs

* [dms.GetShadowData](dms.md#dms.GetShadowData) — reads shadow data back through the
GUID from the history
* [dms.GetObjectHistory](dms.md#dms.GetObjectHistory) — returns the history of an
object with the GUIDs that serve as the key for `dms.GetShadowData`
* [dms.XMLUpdate](dms.md#dms.XMLUpdate) — XML-based index data update; depending on
the configuration, implicitly triggers shadow-data writes
* [std.IndexDataChanged](std.md#std.IndexDataChanged) — signals to the server that
the index data of an object has been changed — downstream components may update the shadow
data accordingly

<a id="dms.XMLCopy"></a>

## dms.XMLCopy

This job copies objects, folders, cabinets and documents can be copied. When copying cabinets or folders, the option [COPYCASCADING](reference/xml_import_reference.md) can be used to determine whether all contained objects should be copied cascading.

When copying a document, it can be copied as a new document or a reference to the original document can be created at the new location. The document will then have two locations, but only one index data record will exist. To link the document in this way, the job option [LINKDOCUMENT](reference/xml_import_reference.md) must be specified. For such a reference copy, the source and target location must differ. This option also applies to all documents copied using the option [COPYCASCADING](reference/xml_import_reference.md).

The parent attributes (registerid, registertype and folderid) are the attributes that identify the new location. The folderid should also be specified even when the new location of the object is a cabinet. The registertype can be determined by the executor, but for performance reasons it should always be specified.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | general options for the job (see Flags) |
| `Options` | STRING | Yes | semicolon-separated job options (e.g. LINKDOCUMENT=1;CHECKACCESS=0) (see [Parameter Options](reference/xml_import_reference.md)) |
| `XML` | BASE64 | Yes | contains object description in XML format (see [DMSData XML Format](xsd/DMSData.md) and the parameter XML) |
| `JobUserGUID` | STRING | Yes | determines the user context (see the parameter JobUserGUID) |

### Input Files

| Name | Description |
|---|---|
| `File_N` | (STRING) Nth file path as alternative to file list |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

No job-specific return values.

> **Note:** The following XML examples always contain all tags and tag attributes that can be used for the respective action. Unused tags or attributes can naturally be omitted.

**XML for creating a new location for a document**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType type="DOCUMENT" internal_name="word_documents" id="-1">
      <Object object_id="28" folder_id="58" register_id="-1" register_type="-1"/>
    </ObjectType>
  </Archive>
</DMSData>
```

<a id="dms.XMLDelete"></a>

## dms.XMLDelete

This job deletes the specified object. Folders, cabinets or documents can be deleted. Fundamentally, there are two types of deletion distinguished by the option [HARDDELETE](reference/xml_import_reference.md):

* 'Physical delete': The object is completely deleted, i.e. not moved to the trash bin. If the object is a document, all its files are also removed from the server.

* 'Delete to trash bin': The object is not physically removed, but is located in the trash bin afterwards and can be restored from there.

An object can have subobjects (e.g. a folder contains documents). This object cannot be deleted if not all its subobjects are deleted. This is controlled by the option [DELETECASCADING](reference/xml_import_reference.md).

Deleting objects assigned to a workflow process is not possible. For the case where a document has multiple locations, the job generally removes the document from all its locations. However, it is also possible to remove the document from exactly one such location. For this, the parent attributes (registerid, register-type or folderid) must be set in the object element. This now represents the location of the document to be removed.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | general options for the job (see Flags) |
| `Options` | STRING | Yes | semicolon-separated job options (e.g. HARDDELETE=1 ;CHECKACCESS=0) (see [Parameter Options](reference/xml_import_reference.md)) |
| `XML` | BASE64 | Yes | contains object description in XML format (see [DMSData XML Format](xsd/DMSData.md) and the parameter XML) |
| `JobUserGUID` | STRING | Yes | determines the user context (see the parameter JobUserGUID) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

No job-specific return values.

> **Note:** The following XML examples always contain all tags and tag attributes that can be used for the respective action. Unused tags or attributes can naturally be omitted.

**XML for deleting a folder**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType internal_name="press_archive_folder" type="FOLDER" id="-1">
      <Object object_id="214"/>
    </ObjectType>
  </Archive>
</DMSData>
```
**XML for deleting a cabinet**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType type="REGISTER" internal_name="file_register" id="-1">
      <Object object_id="229"/>
    </ObjectType>
  </Archive>
</DMSData>
```
**XML for deleting a document**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive internal_name="press_archive" id="-1">
    <ObjectType internal_name="word_documents" maintype="4" cotype="0" type="DOCUMENT" id="-1">
      <Object object_id="214" variantparent_id="-1"/>
    </ObjectType>
  </Archive>
</DMSData>
```

<a id="dms.XMLImport"></a>

## dms.XMLImport

This job enables inserting or updating an object depending on the result of a previous search.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | general options for the job (see Flags) |
| `Options` | STRING | Yes | semicolon-separated job options (e.g. ARCHIVABLE=1;CHECKACCESS=0) (see [Parameter Options](reference/xml_import_reference.md)) |
| `XML` | BASE64 | Yes | contains object description in XML format (see [DMSData XML Format](xsd/DMSData.md) and the parameter XML) with the extension of the `<SearchFields>` tag for search fields. |
| `JobUserGUID` | STRING | Yes | determines the user context (see the parameter JobUserGUID) |
| `[Action0]` | STRING | No | Action to perform when no hits (see action table below) |
| `[Action1]` | STRING | No | Action to perform when one hit (see action table below) |
| `[ActionM]` | STRING | No | Action to perform when multiple hits (see action table below) |

### Input Files

| Name | Description |
|---|---|
| `[FileList]` | Path and name of the documents to be inserted |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `ObjectID` | INT | — | new object ID, if job successful, otherwise -1 |
| `ObjectType` | INT | — | type of the object, otherwise -1 |
| `Hits` | INT | — | number of hits from the search |
| `Action` | STRING | — | performed action. Possible values: `UPDATE`, `INSERT`, `NONE`, `ERROR` |

### Output Files

| Name | Description |
|---|---|
| `[FileList]` | Path and name of the XML file with errors (see Flags) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

### Action Table

| Search Result (Hit Count) | Parameter Name | Possible Parameter Value | Explanation |
|---|---|---|---|
| 0 | `Action0` | `INSERT` (Default) +<br>`NONE` +<br>`ERROR` | Insert (see [dms.XMLInsert](dms.md#dms.XMLInsert)) +<br>Do nothing +<br>Generate error message |
| 1 | `Action1` | `NONE` +<br>`UPDATE` (Default) +<br>`INSERT` | Do nothing +<br>Update object (see [dms.XMLUpdate](dms.md#dms.XMLUpdate)) +<br>Insert at location of found object (see [dms.XMLInsert](dms.md#dms.XMLInsert)) |
| >1 | `ActionM` | `NONE` +<br>`UPDATE` +<br>`INSERT` +<br>`ERROR` (Default) | Do nothing +<br>Update only first object (see [dms.XMLUpdate](dms.md#dms.XMLUpdate)) +<br>Insert at location of first found object (see [dms.XMLInsert](dms.md#dms.XMLInsert)) +<br>Generate error message |
> **Note:** If the object location is specified or restricted, this location is used both for the search and for insertion. The search can also be used to determine the location. If no location is specified and no object is found, inserting a cabinet or document is not possible. In this case, an error message is generated. If no search fields are specified, the object is inserted.

> **Note:** `dms.XMLImport` internally branches into the INSERT or UPDATE path and triggers there the same database side effects as the underlying job.

**Example: Change phone number of contact person**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive internal_name="addresses">
    <ObjectType internal_name="addresses">
      <Object>
        <Search>
          <Fields>
            <Field internal_name="contact_person">Schaumer</Field>
            <Field internal_name="first_name">Harald</Field>
          </Fields>
        </Search>
        <Fields>
          <Field internal_name="phone">0815-12345</Field>
        </Fields>
      </Object>
    </ObjectType>
  </Archive>
</DMSData>
```

<a id="dms.XMLInsert"></a>

## dms.XMLInsert

This job inserts an object into enaio®. A folder, cabinet or document can be inserted. The return parameter 'ObjectID' corresponds to the ID of the added object or is -1 if the job failed. If the object to be inserted is a document and it should have files to be transferred to the archive server, the input file list should be filled with the corresponding file path specifications. Dias can also be transferred this way. If more than one dia is transferred, only the first dia from the list is inserted at the archive server. The location of the new object must be entered in the XML object element in the case of a document or cabinet. If only the cabinet ID is entered here, the cabinet type and archive are automatically determined. However, for performance reasons, these values should always be specified.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | general options for the job (see Flags) |
| `Options` | STRING | Yes | semicolon-separated job options (e.g. ARCHIVABLE=1;CHECKACCESS=0) (see [Parameter Options](reference/xml_import_reference.md)) |
| `XML` | BASE64 | Yes | contains object description in XML format (see [DMSData XML Format](xsd/DMSData.md) and the parameter XML) |
| `JobUserGUID` | STRING | Yes | determines the user context (see the parameter JobUserGUID) |

### Input Files

| Name | Description |
|---|---|
| `[FileList]` | Path and name of the documents to be inserted |
| `File_N` | (STRING) Nth file path as alternative to file list |

### Output Parameters

| Name | Type | Dependency | Description |
|---|---|---|---|
| `ObjectID` | INT | — | new object ID, if job successful, otherwise -1 |
| `ObjectType` | INT | — | type of the object, otherwise -1 |

### Output Files

| Name | Description |
|---|---|
| `[FileList]` | Path and name of the XML file with errors (see Flags) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

> **Note:** The following XML examples always contain all tags and tag attributes that can be used for the respective action. Unused tags or attributes can naturally be omitted.

> **Important:** If important attributes such as e.g. maintype, register_id, register_type or system are not needed, they should either be omitted entirely, set to '0' or '-1', depending on functionality.

> **Important:** The following example with the '<TableFields/>' tags only works if a table is located in the tagging mask for the archive.

> **Important:** The following example with the '<TableFields/>' tags only works if a table is located in the tagging mask for the cabinet.

> **Important:** The following example with the '<TableFields/>' tags only works if a table is located in the tagging mask for the document.

**XML for inserting a folder into an archive**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType id="-1" internal_name="press_archive_folder" type="FOLDER">
      <Object>
        <Fields>
          <Field internal_name="subject_area">Softwareentwicklung</Field>
          <Field dbname="feld2">Testbenutzer</Field>
        </Fields>
        <TableFields>
          <TableField dbname="Tabelle">
            <Row>
              <Field internal_name="designation">Dokumentation</Field>
            </Row>
          </TableField>
        </TableFields>
        <Remarks>
          <RemarkText action="INSERT" color="WHITE">Here a note can be stored.</RemarkText>
          <RemarkObject action="INSERT" object_id="123" object_type="196616">Link note</RemarkObject>
        </Remarks>
      </Object>
    </ObjectType>
  </Archive>
</DMSData>
```
**XML for inserting a cabinet**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType id="-1" internal_name="year_2004" type="REGISTER">
      <Object folder_id="228">
        <Fields>
          <Field internal_name="category">Neuentwicklung</Field>
          <Field osguid="BDED8A3C99E64AD2A4ECBFDB586">öffentlich</Field>
        </Fields>
        <TableFields>
          <TableField internal_name="table_topics">
            <Row>
              <Field internal_name="topic">Dokumentenmanagement</Field>
            </Row>
          </TableField>
        </TableFields>
        <Remarks>
          <RemarkText action="INSERT" color="WHITE">A note for the cabinet.</RemarkText>
          <RemarkObject action="INSERT" object_id="234" object_type="196616">Link note</RemarkObject>
        </Remarks>
      </Object>
    </ObjectType>
  </Archive>
</DMSData>
```
**XML for inserting a document**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType id="-1" maintype="4" cotype="0" internal_name="word_documents" type="DOCUMENT">
      <Object object_id="-1" register_id="78" register_type="0" variantparent_id="-1" maintype="0">
        <Fields>
          <Field system="0" internal_name="author">Testuser</Field>
        </Fields>
        <MultiFields>
          <MultiField system="0" osguid="2AED8A3399EE778DS4ECBFDB582">
            <Page id="1">
              <Value>345</Value>
            </Page>
            <Page id="2">
              <Value>123</Value>
            </Page>
          </MultiField>
        </MultiFields>
        <TableFields>
          <TableField name="Tabelle">
            <Row>
              <Field name="Team">Development</Field>
              <Field internal_name="feld2">
Status: released</Field>
            </Row>
          </TableField>
          <TableField osguid="AAED8A3C99EED78DS4ECBFDB586">
            <Row>
              <Field dbname="fd1">Year 2004</Field>
            </Row>
          </TableField>
        </TableFields>
        <Remarks>
          <RemarkText action="INSERT" color="BLUE">A note for the document.</RemarkText>
          <RemarkObject action="INSERT" object_id="432" object_type="196616">Link note</RemarkObject>
        </Remarks>
      </Object>
    </ObjectType>
  </Archive>
</DMSData>
```

<a id="dms.XMLMove"></a>

## dms.XMLMove

This job moves an object. A cabinet or document can be moved. The parent attributes (registerid, registertype and folderid) are the attributes that identify the new location.

In particular, the folderid should also be specified even when the new location of the object is a cabinet.

When moving a cabinet, it is moved together with its subobjects to the new location. Furthermore, for reference documents, the location must be specified as the 'sourceparent_id' attribute in the Object tag.

Documents can be moved to the user tray. For this, no location specifications in the object element of the XML are required, but the option [WFTOUSERTRAY](reference/xml_import_reference.md) must be activated. The document to be moved must have been in the workflow tray beforehand, documents from folders and cabinets cannot be moved to the user tray.

Documents can be moved from the user tray or workflow tray. These documents can then be moved to a cabinet or folder. The job automatically detects whether the object is in a cabinet, folder, workflow tray or user tray.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | general options for the job (see Flags) |
| `Options` | STRING | Yes | semicolon-separated job options (e.g. ARCHIVABLE=1;CHECKACCESS=0) (see [Parameter Options](reference/xml_import_reference.md)) |
| `XML` | BASE64 | Yes | contains object description in XML format (see [DMSData XML Format](xsd/DMSData.md) and the parameter XML) |
| `JobUserGUID` | STRING | Yes | determines the user context (see the parameter JobUserGUID) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

No job-specific return values.

> **Note:** The following XML examples always contain all tags and tag attributes that can be used for the respective action. Unused tags or attributes can naturally be omitted.

> **Important:** If important attributes such as e.g. id are not needed, they should either be omitted entirely, set to '0' or '-1', depending on functionality.

**XML for moving a cabinet**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType type="REGISTER" internal_name="file_register" id="-1">
      <Object object_id="28" folder_id="58" register_id="-1" register_type="-1"/>
    </ObjectType>
  </Archive>
</DMSData>
```
**XML for moving a document**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType type="DOCUMENT" internal_name="word_documents" maintype="4" cotype="0" id="-1">
      <Object object_id="248" register_id="228" register_type="6488064" folder_id="58"/>
    </ObjectType>
  </Archive>
</DMSData>
```

<a id="dms.XMLMoveType"></a>

## dms.XMLMoveType

This job changes the object type of an existing object and transfers it to a compatible new object type table if necessary.
In contrast to the documented [dms.XMLMove](dms.md#dms.XMLMove) (moving within a hierarchy), this job changes the type association itself — the structure parameters (cabinet, parent ID) follow the `XMLMove` convention.

====
This job is not listed in the official enaio® DMS engine overview. This description was reconstructed from the call code of the `enaio-jobs-custom` template. On the server, the job prefix is uppercase (`DMS.XMLMoveType`); enaio® servers accept both spellings.
====

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | Bitfield (same semantics as `dms.XMLMove`). Default `0`. |
| `XML` | BASE64 | Yes | DMSData XML describing the source object and the new object type (UTF-8). |
| `[Options]` | STRING | No | Optional additional options (same semantics as `dms.XMLMove`). |

### Return Value

`(INT)`: `0` = job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

### See Also

* [dms.XMLMove](dms.md#dms.XMLMove) — moves an object within the cabinet hierarchy (without type change)
* [dms.XMLUnknownToKnown](dms.md#dms.XMLUnknownToKnown) — converts untyped objects to typed objects

<a id="dms.XMLUnknownToKnown"></a>

## dms.XMLUnknownToKnown

This job changes a typeless document to a document with a type. Typeless documents are either in the user tray or workflow tray. For this, either the job option [INWFTRAY](reference/xml_import_reference.md) or [INUSERTRAY](reference/xml_import_reference.md) should be activated, in addition the option 'ISTYPELESS' should be enabled. The type to which the document should be changed is set in the 'ObjectType' tag and the ID of the typeless document is in the 'Object' tag as the 'object_id' attribute.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | general options for the job (see Flags) |
| `Options` | STRING | Yes | semicolon-separated job options (e.g. INWFTRAY=1;CHECKACCESS=0) (see [Parameter Options](reference/xml_import_reference.md)) |
| `XML` | BASE64 | Yes | contains object description in XML format (see [DMSData XML Format](xsd/DMSData.md) and the parameter XML) |
| `JobUserGUID` | STRING | Yes | determines the user context (see the parameter JobUserGUID) |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

No job-specific return values.

> **Note:** The following XML examples always contain all tags and tag attributes that can be used for the respective action. Unused tags or attributes can naturally be omitted.

**XML for typing a typeless document**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType id="-1" internal_name="word_documents" type="DOCUMENT">
      <Object object_id="54">
        <Fields>
          <Field internal_name="author">Testbenutzer</Field>
        </Fields>
      </Object>
    </ObjectType>
  </Archive>
</DMSData>
```

<a id="dms.XMLUpdate"></a>

## dms.XMLUpdate

This job modifies the specified object. A folder, cabinet or document can be updated. If the object to be inserted is a document, file paths can be passed to the file list. Whether these files replace the existing ones or are appended to them is determined by the option [REPLACEFILES](reference/xml_import_reference.md).

Documents can be made into reference documents, as long as they don't have files. This is done by setting the system field 'Foreign ID' (and possibly System ID). For reference documents, the same applies: they can be made into documents again by clearing the Foreign ID (and possibly System ID). This is done by setting the system fields using the 'field_function' attribute with the value 'NULL'.

By specifying the system field 'Owner', the owner can be changed. However, this cannot be specified using the GUID, but must correspond to the username.

If the 'concurrency_timestamp' attribute in the Object tag is filled with a value, it is checked whether the data record has changed since the last retrieval by the caller, and an error is returned. This prevents changes made between retrieval and the desired change from being lost.

By default, rows from table controls are appended to existing data. If the 'line' attribute is set with a row number in the <Row> element, the corresponding row is updated. Row numbering is 1-based. If the job option [REPLACETABLEFIELDS](reference/xml_import_reference.md) is set, all existing rows are completely replaced with the new data.

The job option [REPLACEREMARKS](reference/xml_import_reference.md) determines whether all existing notes and connections are deleted when creating notes or connections, or whether notes and connections are added (Default). 'RemarkText' and 'RemarkObject' have the 'action' attribute with the following values: INSERT (Default), DELETE, UPDATE, UPDATE_TEXT, UPDATE_COLOR. Existing notes are identified by ID (remark_id), connections by object ID and object type ID of the linked object.

### Input Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Flags` | INT | Yes | general options for the job (see Flags) |
| `Options` | STRING | Yes | semicolon-separated job options (e.g. ARCHIVABLE=1;CHECKACCESS=0) (see [Parameter Options](reference/xml_import_reference.md)) |
| `XML` | BASE64 | Yes | contains object description in XML format (see [DMSData XML Format](xsd/DMSData.md) and the parameter XML) |
| `JobUserGUID` | STRING | Yes | determines the user context (see the parameter JobUserGUID) |

### Input Files

| Name | Description |
|---|---|
| `[FileList]` | Path and name of the modified document |
| `[File_N]` | Nth file path as alternative to file list |

### Return Value

`(INT)`: `0` = Job successful, otherwise error code +
[Complete list of error codes](errorcodes.md)

No job-specific return values.

> **Note:** The following XML examples always contain all tags and tag attributes that can be used for the respective action. Unused tags or attributes can naturally be omitted.

**XML for changing a folder**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType id="-1" internal_name="press_archive_folder" type="FOLDER">
      <Object object_id="54">
        <Fields>
          <Field system="0" internal_name="subject_area">Softwareentwicklung</Field>
          <Field dbname="feld2" system="0">Testbenutzer</Field>
        </Fields>
        <TableFields>
          <TableField dbname="Tabelle" system="0">
            <Row>
              <Field internal_name="designation">Dokumentation</Field>
            </Row>
          </TableField>
        </TableFields>
        <Remarks>
          <RemarkText action="INSERT" color="WHITE">A note for the folder.</RemarkText>
          <RemarkObject action="INSERT" object_id="123" object_type="196616">Link text</RemarkObject>
        </Remarks>
      </Object>
    </ObjectType>
  </Archive>
</DMSData>
```
**XML for changing a cabinet**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType id="-1" internal_name="year_2004" type="REGISTER">
      <Object object_id="78">
        <Fields>
          <Field system="0" internal_name="category">Neuentwicklung</Field>
        </Fields>
        <TableFields>
          <TableField internal_name="table_topics">
            <Row>
              <Field internal_name="topic">Dokumentenmanagement</Field>
            </Row>
          </TableField>
        </TableFields>
        <Remarks>
          <RemarkText action="INSERT" color="WHITE">A note for the cabinet.</RemarkText>
          <RemarkObject action="INSERT" object_id="234" object_type="196616">Link text</RemarkObject>
        </Remarks>
      </Object>
    </ObjectType>
  </Archive>
</DMSData>
```
**XML for changing a document**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive id="-1" internal_name="press_archive">
    <ObjectType id="-1" maintype="4" cotype="0" internal_name="word_documents" type="DOCUMENT">
      <Object object_id="221" register_id="-1" variantparent_id="-1" maintype="0">
        <Fields>
          <Field system="0" internal_name="author">Testuser</Field>
        </Fields>
        <MultiFields>
          <MultiField system="0" osguid="2AED8A3399EE778DS4ECBFDB582">
            <Page id="1">
              <Value>345</Value>
            </Page>
            <Page id="2">
              <Value>123</Value>
            </Page>
          </MultiField>
        </MultiFields>
        <TableFields>
          <TableField name="Tabelle">
            <Row>
              <Field name="Team">Development</Field>
              <Field internal_name="feld2">Status: released</Field>
            </Row>
          </TableField>
          <TableField osguid="AAED8A3C99EED78DS4ECBFDB586">
            <Row>
              <Field dbname="fd1">Year 2004</Field>
            </Row>
          </TableField>
        </TableFields>
        <Remarks>
          <RemarkText action="INSERT" color="BLUE">A note for the document.</RemarkText>
          <RemarkObject action="INSERT" object_id="432" object_type="196616">Link text</RemarkObject>
        </Remarks>
      </Object>
    </ObjectType>
  </Archive>
</DMSData>
```

<a id="Object Type ID"></a>

## Object Type ID

The numeric **object type ID** uniquely identifies every object type in enaio® (folders, registers, documents, portfolios, notes). In the API it appears, among others, as the parameter `objecttypeid` (e.g., [mng.ExportSecuritySystem](mng.md#mng.ExportSecuritySystem)), as the XML attribute `id` on `<ObjectType>` ([DMSContent](xsd/DMSContent.md), [DMSData](xsd/DMSData.md) documents), as the return value `ObjectType` from [dms.GetObjectTypeByID](dms.md#dms.GetObjectTypeByID), and as the attribute `object_type` in security system XML structures.

### Computation

The object type ID is composed of two 16-bit parts:

```text
objecttypeid = (maintype << 16) | cotype
```
* `maintype` — Highword (upper 16 bits): classifies the broad kind of object type.
* `cotype` — Lowword (lower 16 bits): running subtype index within the class, starting at `0`.

Both parts can be recovered from a given object type ID:

```text
maintype = (objecttypeid >> 16) & 0xFFFF
cotype   =  objecttypeid        & 0xFFFF
```

### Main Types (`maintype`)

| Object Type | `maintype` (dec) | `maintype` (hex) | `cotype` Range |
|---|---|---|---|
| Folder | `0` | `0x0000` | `>= 0` |
| Document — Grayscale | `1` | `0x0001` | `>= 0` |
| Document — Black/White | `2` | `0x0002` | `>= 0` |
| Document — Color | `3` | `0x0003` | `>= 0` |
| Document — Windows | `4` | `0x0004` | `>= 0` |
| Document — Multimedia | `5` | `0x0005` | `>= 0` |
| Document — E-Mail | `6` | `0x0006` | `>= 0` |
| Document — XML | `7` | `0x0007` | `>= 0` |
| Document — Container | `8` | `0x0008` | `>= 0` |
| Register | `99` | `0x0063` | `>= 0` |
| Typeless document in user tray | `200` | `0x00C8` | `1`–`7` (document main type) |
| Typeless document in workflow tray | `300` | `0x012C` | `1`–`7` (document main type) |
| Portfolio | `203` | `0x00CB` | `0` |
| Note | `32767` | `0x7FFF` | `1`–`4` |

### Examples

| `objecttypeid` | `maintype` | `cotype` | Meaning |
|---|---|---|---|
| `0` | `0` | `0` | First cabinet folder |
| `1` | `0` | `1` | Second cabinet folder |
| `262144` (`0x040000`) | `4` | `0` | First Windows document |
| `262145` (`0x040001`) | `4` | `1` | Second Windows document |
| `6488064` (`0x630000`) | `99` | `0` | First register |
| `6488067` (`0x630003`) | `99` | `3` | Fourth register / subregister |

### Runtime Resolution

At runtime an object type ID can be resolved against the object definition:

* [dms.GetObjectTypeByID](dms.md#dms.GetObjectTypeByID) returns the `ObjectType` directly for an object ID.
* [dms.GetObjDef](dms.md#dms.GetObjDef) returns the full object definition with cabinets, object types and fields. From it the internal name, display name and underlying database table can be derived for a given object type ID.

The XSD schemas in [DMSObjDef](xsd/DMSObjDef.md) and [DMSContent](xsd/DMSContent.md) describe the `maintype`/`cotype` attributes at the XML level.

### See Also

* [dms.GetObjectTypeByID](dms.md#dms.GetObjectTypeByID)
* [dms.GetObjDef](dms.md#dms.GetObjDef)
* [DMSObjDef](xsd/DMSObjDef.md)
* [DMSContent](xsd/DMSContent.md)
* [DMSData](xsd/DMSData.md)