Web Service

This activity allows you to integrate REST or SOAP web services in your workflow. Web services can be used to automatically exchange data between systems or to create, update, or delete information in other applications via workflow.

Conversely, you can use data from other programs in your workflows. For example, connect your financial accounting system or CRM to DocuWare. To use web services with Workflow Manager, first register them in DocuWare Configuration under Web Services.

The Web Services activity in Workflow Designer provides you with an assisted structure with a workflow type for creating the web service call. The most important steps are illustrated here using the example of a REST web service.

1. General

First select the REST web service and specify the format for data exchange (JSON or XML). The services that were previously set up under Web services in DocuWare Configuration are available for selection. Any further required information will differ depending on the web service type selected.

If your web service offers an OpenAPI specification file (*.json, *.txt, *.yml or *.yaml), you have the option to import it. Once imported, all available endpoints are listed in the dropdown:

DocuWare Web Service Activity 1

2. Request

Select the method and configure the HTTP request. A preview of the request (URL) is displayed at the top. You have the flexibility to design the URL path, define query parameters, and structure HTTP body content using either fixed values, indexed data, or global and system variables.

Finally, test the request using the "Send" button and examine the "Response" to verify the success of the operation. Keep in mind that you need to provide a test value for each variable to run the test.

DocuWare Web Service Activity 2

HTTP body

On the HTTP body tab, you have the option of attaching the current document to the HTTP request to an external RESTful web service. This allows you, for example, to send a saved document such as an invoice to an external AI capture service to capture the document and assign the captured information to index fields or global variables.

The document can be exported as an original document or as a pdf without annotations. If the DocuWare document contains multiple files (clipped), all files are exported and attached separately. The HTTP request then contains several file objects.

Validation of HTTP Body

Validation of the HTTP body is performed either with Send or automatically when saving the configuration. If any part of the content is found to be invalid, the specific error is highlighted, and a corresponding message is displayed.
It's important to note that even if there are validation issues, you still have the option to save the configuration.

Encoding HTTP requests

There are three options to choose from when encoding HTTP requests:

  1. Encode special characters (recommended): All special characters are encoded, e.g. "AT&T" becomes "AT%26T" and "Rapid Transport" becomes "Rapid%20Transport"

  2. Encode special characters except reserved URL characters: ?#[]@!$&/*+,;='() Except for the reserved URL characters, all special characters are encoded, e.g. "AT&T" remains, but "Rapid Transport" becomes "Rapid%20Transport."

  3. Do not encode special characters: Neither special characters nor spaces are encoded.

The encoding is applied to all values whose transfer is specified on the Route and Queries tabs, but not to the values of the HTTP Header and HTTP Body tabs.

Configuring endpoints

In case you use an OpenAPI specification file or the default REST web service "DocuWare Platform API", configure the endpoint selected in the previous step. To simplify the configuration all required parameters are automatically pre-set based on the chosen endpoint.

For the DocuWare Platform API, specifically, within the Route and Queries sections you define missing values, for example the file cabinet or document to be accessed.

In the HTTP Body section specify the required information and properties needed to execute the selected operation, for example the GUID of the stamp to be placed.

3. Data Assign

In this step, assign values from the response to either global variables or index data. Choose the necessary values directly from the JSON or XML using a tree view interface (see below).

This enables you to extract and store specific information from the response for further utilization within your workflow.
WFDes_Webservice_3

pictemplate_small

If you aim to handle all returned entries, manually replace the index with an asterisk (*) in the array indexer. This allows for comprehensive processing of all entries within the array.

DocuWare Web Service Activity 5

Default web service DocuWare Platform API

Access your file cabinets and documents in the file cabinets via the integrated default web service DocuWare Platform API.

The list below shows the available endpoints for the default REST web service "DocuWare Platform API".

In der Liste unten finden Sie die Endpunkte, die für DocuWare Platform API bereits verfügbar sind.

! Some endpoints can execute multiple operations !

For example, the endpoint "documentAnnotations" places a stamp on a free or a fixed position or adds a text annotation.

The path/endpoint is the same for these three functions with “documentAnnotations”. The difference is the HTTP body. However, DocuWare can only automatically pre-populate one HTTP body.

For the “documentAnnotations” example, the HTTP body for the “Add stamp to an automatically defined position” function is filled in by default. If you want to use a different function with “documentAnnotations”, you have to manually replace and adjust the HTTP body. The corresponding templates can be found at the bottom of the list of endpoints.

The line "Default" in the list of endpoints indicates which HTTP Body is pre-filled automatically.

Check this overview to find the operations that share the same path/endpoint:

  • documentAnnotations

    POST /FileCabinets/{TrayId/FileCabinetId}/Operations/ProcessDocumentAction?docId={DocId}

    • Add stamp to an automatically defined position - default

    • Add stamp to a fixed position

    • Add text annotation to a fixed position

  • processDocumentAction

    PUT /FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}/Annotation

    • Merge layers - default

    • Append a document

  • userRoles

    PUT /Organization/UserRoles?UserId={UserId}

    • Add user to a role - default

    • Remove user from a role

  • userGroups

    PUT /Organization/UserGroups?UserId={UserId}

    • Add user  to a group - default

    • Remove user from a role

To pass the ID/GUID of a user, simply write the username into a global variable of type "User" and pass the variable in the HTTP request. The system will automatically provide the appropriate GUID.

List of endpoints

Get total amount of documents in a file cabinet or document tray

  • Description: DialogId (optional): The identifier of the used search dialog.
    FieldName (optional): The name of the field whose values are grouped and counted.

  • Default: yes

  • Operation: countResult

  • Command: POST

  • Route/Path:
    /DocuWare/Platform/FileCabinets/ {TrayId/FileCabinetId}/Query/CountExpression?dialogId={DialogId}&fieldName= {FieldName}

Search by dialog

  • Description: DialogId (optional): The identifier of the used search dialog.

  • Default: yes

  • Operation: dialogExpression

  • Command: POST

  • Route/Path:
    /DocuWare/Platform/FileCabinets/ {TrayId/FileCabinetId}/Query/CountExpression?dialogId={DialogId}&fieldName= {FieldName}

  • HTTP body (sample): 

    { "Condition":[ {"DBName":"COMPANY", "Value":["Peter's Engineering"]},{"DBName":"CONTACT", "Value":["EMPTY()"]},{"DBName":"DocuWareFulltext", "Value":["Solar Panels"]}], "Operation":"And"}

Create a new database entry in a document tray or a file cabinet

  • Default: yes

  • Operation: documents

  • Command: POST

  • Route/Path: /FileCabinets/{TrayId/FileCabinetId}/Documents

  • HTTP body (sample): 

    { "Fields": [ { "FieldName": "COMPANY", "Item": "Peter's Engineering" }, { "FieldName": "CONTACT", "Item": "Peter Sanders" }, { "FieldName": "DOCUMENT_DATE", "Item": "2020-01-01" }, { "FieldName": "COST_CENTER", "Item": { "$type": "DocumentIndexFieldKeywords", "Keyword": [ "A", "B", "C" ] } } ] }

Get information of a document

  • Default: yes

  • Operation: document

  • Command: GET

  • Route/Path: /FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}

Delete a document

  • Default: yes

  • Operation: documentDelete

  • Command: DELETE

  • Route/Path: /FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}

Delete a section of a document

  • Description: The only section of a document is deleted it will automatically be converted to a database entry.

  • Default: yes

  • Operation: sectionDelete

  • Command: DELETE

  • Route/Path: /FileCabinets/{TrayId/FileCabinetId}/Sections/{SectionId}

Add a stamp at an automatically defined position

  • Description: Add stamp on best position.

  • Default: yes

  • Operation: documentAnnotations

  • Command: POST

  • Route/Path: /FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}/Annotation

  • HTTP-body (sample): 

    { "Annotations": [ { "PageNumber": 0, "SectionNumber": 0, "AnnotationsPlacement": { "Items": [ { "$type": "StampPlacement", "StampId": "73d54f34-1b80-4b43-81ec-f0d31176d990", "Layer": 1, "Field": [ { "Name": "<#1>", "TypedValue": { "Item": "*Test007*" }, "Value": "Jenkins" }, { "Name": "<#2>", "TypedValue": { "Item": "*Test007*" }, "Value": "Approved" } ], "Password": null } ] } } ] }

Add a stamp on fixed position

  • Operation: documentAnnotations

  • Command: POST

  • Route/Path: FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}/Annotation

  • HTTP body (sample): 

    { "Annotations": [ { "PageNumber": 0, "SectionNumber": 0, "AnnotationsPlacement": { "Items": [ { "$type": "StampPlacement", "Location": { "X": "100", "Y": "100" }, "StampId": "6ab67774-074d-4d93-99c5-5bc46262b84c", "Layer": 1, "Field": [ { "Name": "<#1>", "TypedValue": { "Item": "September" }, "Value": "Sep." } ], "Password": null } ] } } ] }

Add text annotation

  • Operation: documentAnnotations

  • Command: POST

  • Route/Path: FileCabinets/{TrayId/FileCabinetId}/Documents/{DocId}/Annotation

  • HTTP body (sample): 

    { "Annotations": [ { "PageNumber": 0, "SectionNumber": 0, "AnnotationsPlacement": { "Items": [ { "$type": "Annotation", "Layer": [ { "Id": "1", "Items": [ { "$type": "TextEntry", "Font": { "FontName": "Lucida Console", "Bold": true, "Italic": true, "Underlined": false, "StrikeThrough": false, "FontSize": 200, "Spacing": 0 }, "Value": "Test annotation", "Location": { "Left": 100, "Top": 100, "Width": 1500, "Height": 500 }, "Color": "Black", "Rotation": 0, "Transparent": false, "StrokeWidth": 50 } ] } ] } ] } } ] }

Transfer a document

  • Description: Transfer document from a source file cabinet or document tray to the specified file cabinet or document tray

    Content type has to be set to application/vnd.docuware.platform.documentstransferinfo+json

  • Default: yes

  • Operation: transfer

  • Command: POST

  • Route/Path: /FileCabinets/ {TrayId/FileCabinetId} /Task/Transfer

  • HTTP body (sample): 

    { "SourceFileCabinetId": "ae156510-ffa8-48b1-a3ec-baec3180669c", "Documents": [ { "Id": 123456, "Fields": null } ], "KeepSource": true, "FillIntellix": false,"UseDefaultDialog": true}

Replace a file of a document

  • Description: Replace the file of a document with the document within the workflow.

  • Default: yes

  • Operation: sectionData

  • Command: POST

  • Route/Path: /FileCabinets/{TrayId/FileCabinetId}/Sections/{SectionId}/Data

Append a new file

  • Description: Append a the current document to another document in a file cabinet or document tray

    Document can be appened in original format or as PDF without annotations or stamps.

    If the target is a DB entry it will automatically be converted to a document.

  • Default: yes

  • Operation: sections

  • Command: POST

  • Route/Path: /FileCabinets/{TrayId/FileCabinetId}/Sections?DocId={DocId}

Merge layers

  • Description: Merge the annotation layers with the document. This will create new PDF and replace the old one.

  • Default: yes

  • Operation: processDocumentAction

  • Command: PUT

  • Route/Path:
    /FileCabinets/{TrayId/FileCabinetId}/Operations/ProcessDocumentAction?docId={DocId}

  • HTTP body (sample): 

    { "DocumentAction": "MergeAnnotations","DocumentActionParameters":{"$type":"MergeAnnotationsParameters","SectionNumber":0}}

Append a document

  • Description: DialogId (optional): The identifier of the used search dialog. FieldName (optional): The name of the field whose values are grouped and counted.

  • Operation: processDocumentAction

  • Command: PUT

  • Route/Path:
    /FileCabinets/{TrayId/FileCabinetId}/Operations/ProcessDocumentAction?docId={DocId}

  • HTTP body (sample): 

    { "DocumentAction": "Append", "DocumentActionParameters": { "$type": "AppendActionParameters", "RemoveSourceDocuments": false, "DocumentsInFront": [ ], "DocumentsAtBack": [ { "SourceCabinetId": "ae156510-ffa8-48b1-a3ec-baec3180669c", "Documents": [ 123456 ] } ] } }

Create user

  • Description: Content type has to be set to application/vnd.docuware.platform.createorganizationuser+json

  • Default: yes

  • Operation: createUser

  • Command: POST

  • Route/Path: /Organization/UserInfo

  • HTTP body (sample): 

    { "EMail": "firstname.lastname@domain.com", "Name": "MyUserName", "DBName": "MYUSERNA", "Password": "eLK%4s*Z", "NetworkID": "Domain\\MyUserName" }

Modify user properties

  • Default: yes

  • Operation: modifyUser

  • Command: PATCH

  • Route/Path: /Organization/UserInfo

Get all users of the organization

  • Default: yes

  • Operation: users

  • Command: GET

  • Route/Path: /Organization/Users?Active={true|false}&Name={UserName}

Get all users of a group

  • Description: GroupID (required): The identifier of the group.

  • Default: yes

  • Operation: usersByGroup

  • Command: GET

  • Route/Path: /Organization/GroupUsers?groupId={GroupId}

Get all users of a role

  • Description: RoleID (required): The identifier of the group.
    IncludeGroupUsers (optional): Boolean - default: 'false'

  • Default: yes

  • Operation: usersByRole

  • Command: GET

  • Route/Path:
    /Organization/UserRoles?UserId={UserId}&Active={true|false}&Name={RoleName}&Type={Standard|Default|Administrator}

Get information of a user

  • Description: Gt the properties of a specific user such as active state or out of office state.

    UserID (required):

    The identifier of the user.

  • Default: yes

  • Operation: userById

  • Command: GET

  • Route/Path: /Organization/UserByID?userId={UserId}

Get all roles of a user

  • Description:
    UserID (required): The identifier of the user.

    Active (optional): Boolean - default: empty

    Name (optional): The name of the role

    Type (optional): {Standard|Default|Administrator}

  • Default: yes

  • Operation: userRoles

  • Command: GET

  • Route/Path: /Organization/UserRoles?UserId={UserId}

Add a user to role

  • Description: UserID (required): The identifier of the user.

  • Default: yes

  • Operation: userRoles

  • Command: PUT

  • Route/Path: Organization/UserRoles?UserId={UserId}

  • HTTP body (sample): 

    { "Ids": [ "2d89fc45-a3c4-49c6-971b-ebc696a67d78" ], "OperationType": "Add" }

Remove user from role

  • Description: UserID (required): The identifier of the user.

  • Operation: userRoles

  • Command: PUT

  • Route/Path: Organization/UserRoles?UserId={UserId}

  • HTTP body (sample): 

    { "Ids": [ "2d89fc45-a3c4-49c6-971b-ebc696a67d78" ], "OperationType": "Remove" }

Get all groups of a user

  • Description:
    UserID (required): The identifier of the user.

    Active (optional): Boolean - default: empty

    Name (optional): The name of the group

  • Default: yes

  • Operation: userGroups

  • Command: GET

  • Route/Path: /Organization/UserGroups?UserId={UserId}

Add a user to a group

  • Description: UserID (required): The identifier of the user.

  • Default: yes

  • Operation: userGroups

  • Command: PUT

  • Route/Path: /Organization/UserGroups?UserId={UserId}

  • HTTP body (sample): 

    { "Ids": [ "2d89fc45-a3c4-49c6-971b-ebc696a67d78" ], "OperationType": "Add" }

Remove user from a group

  • Description: UserID (required): The identifier of the user.

  • Default: yes

  • Operation: userGroups

  • Command: PUT

  • Route/Path: /Organization/UserGroups?UserId={UserId}

  • HTTP body (sample): 

    { "Ids": [ "2d89fc45-a3c4-49c6-971b-ebc696a67d78" ], "OperationType": "Remove" }

Get all roles from the organization

  • Description:
    Active (optional): Boolean - default: empty

    Name (optional): The name of the role

    Type (optional): {Standard|Default|Administrator}

  • Operation: roles

  • Command: GET

  • Route/Path: /Organization/Roles? Active={true|false}&Name={RoleName}&Type={Standard|Default|Administrator}

Get information of a role

  • Description:
    Get the information of a role such as active state

    RoleID (required): The identifier of the role.

  • Default: yes

  • Operation: role

  • Command: GET

  • Route/Path: /Organization/Role?roleId={RoleId}

Get all groups from the organization

  • Description:
    Active (optional): Boolean - default: empty

    Name (optional): the name of the group

  • Default: yes

  • Operation: groups

  • Command: GET

  • Route/Path: /Organization/Groups?&Active={true|false}&Name={GroupName}

Get information of a group

  • Description:
    Get the information of a group such as active state.

    GroupID (required): The identifier of the group.

  • Default: yes

  • Operation: group

  • Command: GET

  • Route/Path: /Organization/Group?groupId={GroupId}

Sample use case for setting a stamp with endpoint "documentAnnotations"

After an invoice has been processed in the accounting software, you want to automatically set a "Paid" stamp on the invoice in DocuWare.

To do this, create an Autoindex job which changes the index entry of the invoice to "paid". The change of the index entry of the invoice triggers a workflow, whose web service activity automatically puts the "Paid" stamp on the invoice document.

Note that the "Paid" stamp must be configured and assigned to the user which is specified for the workflow to run automatic activities.

The configuration of the "documentAnnotations" endpoint looks like this:

Web service platform table example

Web service platform table example 2

Web service platform table example 3