Document

Full-Text Search

The search for the full text of a document, as known from the controls, can be initiated with the following command:

var docIds = await dms.Document.FilterDocumentIds(searchString);

FilterDocumentIds

This method can be called with a simple or a complex filter. Filters are used to search for documents based on the index data stored in the database (NOT full text). A complex filter is a combination of several (including hierarchical) simple filters.

Simple Filters

var filter = new SimpleExpression(operator, field, value);
var documentIds = await dms.Document.FilterDocumentIds(filter);

Optionally, a sort order can be specified for the filter. To do this, create a list (1st, 2nd, … sort field) with fields by which the result should be sorted. For each field, you can specify whether it should be sorted in ascending or descending order.

var orders = new List<OrderDefinition>();
orders.Add(new OrderDefinition() 
{
    Fieldname = STP.Ecm.ApiCore.Fieldname.Document.Title,
    Direction = OrderDirection.Ascending
});
// Load all document IDs sorted by title that are in the file 01/2021
var filter = new SimpleExpression(
                     SimpleOperator.Equals, 
                     STP.Ecm.ApiCore.Fieldname.Dossier.Filenumber,
                     "01/2021");
var sortedDocumentIds = await dms.Document.FilterDocumentIds(filter, order);

Simple filters allow searches for values from exactly one field. If multiple fields or multiple values of a field need to be considered, complex filters must be used.

Complex Filters

With this, multiple SimpleExpression elements can be combined using And/Or. A ComplexExpression element can contain a list of simple expressions (SimpleExpression) and/or a list of complex expressions, allowing for a tree structure.

Example of searching for documents in a specific file that have the document category "Red" or "Blue" set:

var filter = new ComplexExpression(ComplexOperator.And);
var categoryFilter = new ComplexExpression(ComplexOperator.Or);
categoryFilter.SimpleExpressions.Add(new SimpleExpression(
                   SimpleOperator.Equals,
                   STP.Ecm.ApiCore.Fieldname.Document.Category,
                   "Red Category"));
categoryFilter.SimpleExpressions.Add(new SimpleExpression(
                   SimpleOperator.Equals,
                   STP.Ecm.ApiCore.Fieldname.Document.Category,
                   "Blue Category"));
filter.ComplexExpressions.Add(categoryFilter);

filter.SimpleExpressions.Add(new SimpleExpression(
                   SimpleOperator.Equals,
                     STP.Ecm.ApiCore.Fieldname.Dossier.Filenumber,
                     "01/2021"));

Restriction by Topics

A filter can also be limited to one or more topics. For this, a list of topic names (internal names, not display names) is provided as the third parameter.

For example, to search for documents in the knowledge base whose title starts with “Article,” you would use the following:

var filter = new SimpleExpression(
                     SimpleOperator.Like,
                     STP.Ecm.ApiCore.Fieldname.Document.Title, 
                     "Article%");
var documentIds = await dms.Document.FilterDocumentIds(
                     filter, 
                     null, 
                     new [] { "Jurathek" });

Sorting

If you already have a list of document IDs and want to reorder them, you can do so with the following call (here, sorting by title).

var orders = new List<OrderDefinition>();
orders.Add(new OrderDefinition() 
{
    Fieldname = STP.Ecm.ApiCore.Fieldname.Document.Title,
    Direction = OrderDirection.Ascending
});
var sortedIds = await dms.Document.SortIds(unsortedIds, orders);

Import

//Import sets document class:
var docDto = new DmsDocumentDto{
                 DocumentClass = @"stp.wza.claim"
             };

dms.Document.Import(FileInfo file, DmsDocumentDto docDto)

Import document with DmsDocumentDto.

dms.Document.Import(localFileInfo, title, containerId)

This allows for easy document import.

dms.Document.Import(Stream stream, DmsDocumentDto docDto)

Import document with stream content and DmsDocumentDto.

Import and Update Rendition

Import and/or update the rendition of a document with DocumentRenditionDto.

dms.Document.ImportNewOrUpdateRendition(renditionDto, stream)

This allows for easy import of a rendition for a document version into the RenditionStore. The content is provided via a stream. Filling out the DocumentRenditionDto: |Value|Meaning| |-|-| |Type|Rendition type, e.g., “ocr” as a (free) string| |DocumentId|The GUID of the document in the DMS.| |DocVersion|The version number of the document to which the rendition belongs.| |Extension|The file name extension as a free string.|

The properties UpdateCount, Created, ContentSize are return values.

The return type is RenditionResultDto. Additionally, it includes the fields Error (string) and Success (bool).

For these operations, notifications of type NewRenditionCreated or RenditionChanged are sent with the RenditionResultDto.

Download Content Directly into Stream

To save the content of a document into a stream without using a local file, use the following call:

var success = await dms.Document.DownloadContent(documentId, StreamContents = stream =>
                    {
                        //Read content from stream!
                    });

Download Content

To save the content of a document locally, use the following call:

var success = await dms.Document.DownloadContent(documentId, targetFilePath);

The targetFilePath is a file name used to save the document locally. The file name must be fully specified, including the complete path with the correct file extension. The above call saves the latest version of the document in its original format under the specified file name.

If you want to save a PDF version or another version, download options can be specified.

var config = new DocumentDownloadConfig();
config.Version = DocumentVersionIdentifier.Specific(1);
config.Format = DocumentDownloadFormat.Pdf;
dms.Document.DownloadContent(documentId, targetFilePath, config);

This downloads the first (oldest) version of the document as a PDF.

The following values from DocumentDownloadFormat are available for formats:

Note on PdfA: If the output format is PdfA, the setting for the beA export applies, especially the file types excluded there. If a type specified there is to be converted to PDF-A, the API throws an exception.

Load Document Data

To load the data (not the content) for one or more documents, use the following call:

var documentDatas = await dms.Document.LoadDocumentData(listOfIds);

It's advisable not to load several thousand entries here, but to request lists only in blocks of up to 400 entries.

Field ‘Format’

In documentData and DmsDocumentVersionDto, there is a field ‘Format’. The ‘Format’ field currently (DMS Version 8.6.1) contains only two values, namely ‘PDF/A’ and ‘XRechnung’.

Retrieve List of Renditions for a Document

In documentData, there is also the list of all renditions as List<DocumentRenditionDto>. Additionally, the data for the versions DmsDocumentVersionDto also each contain a list of renditions.

Change Document Data

You can change the data of a document with the Update command. The document ID is required, along with a list of changes to be applied. ### UpdateCount For the “Update” method, there is a new variant with an UpdateCount to ensure transactional safety. The old method is obsolete and will be removed in a future version. (LoadDocument() loads this UpdateCount in the Dto.)

var changes = new List<FieldUpdateInfo>();
changes.Add(new FieldUpdateInfo() {
    FieldKey = STP.Ecm.ApiCore.Fieldname.Document.Title,
    Value = "New Title"
});

//Change document class:
changes.Add(new FieldUpdateInfo(){
            FieldKey = Fieldname.Document.Class,
            Value = "stp.wza.claim"
       });

var resultDocumentId = await dms.Document.Update(documentId, updateCount, changes);

If the update is successful, the return value is set to DocumentId. If a conflict occurs, the return value is null.

Move Document

This allows documents to be moved to another register.

var moveInfos = await dms.Document.Move(documentIds, targetContainerId, targetTrayId);

Documents can also be moved across file boundaries, but the index data will be lost in the process. As a result, the outcome of the move is returned for each specified document. The info includes:

Mark Document for Deletion

When a document is marked for deletion, it moves to the user's trash. The following method is available for this:

var success = await dms.Document.MarkDocumentForDelete(listOfDocumentIds);

To restore the documents from the trash to their original location, call this:

var success = await dms.Document.UnmarkDocumentForDelete(listOfDocumentIds);

Important: This method does not support server-side impersonation. The deletion mark is always set with the user who initially instantiated the API.

Delete Rendition(s) of a Document

To delete renditions, the following method is available:

var success = await dms.Document.DeleteRenditions(listOfDocumentRenditionDtos);

Similar to the import, the data structure DocumentRenditionDto specifies the rendition(s) to be deleted. The key properties are: Id, DocumentId, DocVersion, Type. The return is a list of type RenditionResultDto. Additionally, the fields Error (string) and Success (bool) are included.

The following cases are distinguished for the deletion request per DocumentRenditionDto: - If the Id is specified, the single rendition is specified. Only this rendition will be deleted. The document and version are implicitly known. - If the DocumentId, DocVersion, and Type are specified, a single rendition is specified. - If the DocumentId and DocVersion are specified, all renditions for this document version are deleted. - If the DocumentId and Type are specified, all renditions of this type in all versions of the document are deleted. - If only the DocumentId is specified, all renditions (in all versions) are deleted.

The specification of the DocumentId is required unless the rendition's Id is provided.

For these operations, a notification of type RenditionDeleted is sent with the RenditionResultDto for each deleted rendition.

Change Document Content

To change (edit) the content of the document, it must be checked out. This means it will be permanently locked for other users. With the command

var edit = await dms.Document.Checkout(documentDto, targetFilePath);

you get an edit object. The document is thus locked, and the current content is saved locally under the specified file name (targetFilePath).

Through the edit object, changes cannot be made directly to the document, but the changes made to the file by an external editor like Word/Excel/... can be brought back into the DMS.

If the checkout was done in a previous session, it can also be resumed and continued.

var edit = await dms.Document.ReattachToCheckout(documentDto, targetFilePath);

The checkout is not performed again, but the following conditions must exist: 1. The file specified under targetFilePath must exist. 2. The document must be permanently locked in DMS for the logged-in or impersonated user.

Save

With edit.Save(), an interim save is performed. The current content of the file is transferred to DMS and overwrites the current content. The document remains checked out, i.e., locked.

Cancel Editing

With edit.DropChanges(), the processing is canceled. The local file becomes useless, and the document on the server is released (unlocked).

Finish with Overwrite

This essentially corresponds to Save(), except that the editing is finished, and the document on the server is released again.

edit.FinishWithOverwrite();

Finish with New Version

This also completes the editing. However, the current content of the file is imported as a new version into the document. Optionally, a comment can be added directly to the method.

edit.FinishWithNewVersion("edited as discussed");

Use Local File as New Version

An entirely independent local file can also be used as a new version for the document. This completes the editing and uses the specified file as the content for the new version.

edit.FinishWithNewVersionAndNewContent(localFilename);

This can be used, for example, when changing the format to PDF.

Change Title and Comment

A title and comment can be set on the edit object. For all actions (except DropChanges), these values, if set, will be applied.

Attach Attachments

Set

Attachments can be clipped to a document. For example, in an email, the additionally imported attachment documents.

bool success = await dms.Document.ClipAttachmentsToDocument(idOfDocument, idsOfAttachments, CLipType.eMail);

The idOfDocument is the ID of the main document to which the attachments should be clipped. Typically, this is the email or a beA message. idsOfAttachments is a list of document IDs of the documents that should be attached to the main document. The third parameter specifies the type of attachment. Available values are:

If the clipping is successful, true is returned as the result.

Query

The attachments to a document can be queried with the following call:

var modus = HierarchyModus.DirectAttachmentsOnly;
var attachedDocumentIds = await dms.Document.GetAttachments(documentId, modus);

The result list contains the document IDs of all attached documents that have been set using the clipping method. Note: The context menu call in the DMS clients can also bring emails together through their process. This is not possible with this method. The list contains elements of type AttachmentReference:

Clipping is always additive. It can be called multiple times for a main document. This increases the list of attachments. If attachment documents are already assigned as attachments, they will not be reassigned.

Hierarchy Mode (from DMS 7.5.2002)

When querying, a hierarchy mode can be specified. This indicates how hierarchical attachment structures should be searched starting from the specified document.

Main Document (No. 1)
- Attachment 1 (No. 2)
- Attachment 2 (No. 3)
- Attachment 3 (No. 4)
   - Attachment 3.1 (No. 6)
       - Attachment 3.1.1 (No. 7)
- Attachment 4 (No. 5)

If you have such a structure and call the method, for example, for the document with number 4 ("Attachment 3"), you have 3 different options for how the result list is compiled using the mode:

In the case of EntireStructure, the main document is first searched from the specified document. This has no parent document. From there, the complete hierarchy is returned. In the flat list, the respective attachments are always inserted directly after the respective parent document. Therefore, 6 and 7 also come directly after 4 and only then 5.

Effects

If an attachment relationship is established for a document, it can be queried via the AnhangStatus field on the document object (DmsDocumentDto). The field is of type Int32 and can contain the following values: |AnhangStatus|Meaning| |-|-| |0|Document has no attachment relationship.| |1|The document has attachments.| |2|The document is an attachment of another document.| |3|The document is an attachment and has its own attachments.|

Create Log Entry

Dms logs most actions through which a document can be accessed. The API allows additional entries to be added to the log so that further actions with a downloaded document content can be recorded.

var reason = CheckoutReason.Print;
dms.Document.AddProtocolEntry(documentId, documentVersion, reason);

In this case, it indicates that the document was printed. The log entry is automatically supplemented with the current timestamp and the logged-in user.