DocuWare Upload

The DocuWare Upload plugin uploads a single file of any file type to a dedicated DocuWare CRM system with related index information.

DocuWare is organized in so called "File Cabinets", where each cabinet can have its own, specific set of index fields. This plugin allows defining of the target File Cabinet and respective index values.

Installation

This plugin is not installed with Workflow, but it is available for free to download from the Resource Center (https://olresourcecenter.uplandsoftware.com).

After downloading the .PPK file, you will then need to import it into Workflow yourself. See Importing a plugin.

Once imported, the DocuWare Upload plugin will appear in the Document Management category within the Plug-In Bar.

To be able to use this plugin you need a working DocuWare installation and user account with appropriate permissions.

Input

The input of this plugin can be a file of any type.

Processing

After establishing a connection with the DocuWare system, the plugin will try to upload the specified file (either the Job File, or an external file) with the given index values to the selected File Cabinet. The plugin won't modify the uploading file in any way.

If any issue is detected during a file upload, the log messages and the related file and its index values will be stored.

The Docuware Upload plugin is designed to work offline as well as online. Once a Test Connection has been established, the Cabinet and Index data will be downloaded and stored locally. This allows authoring of Workflow configurations without requiring a constant live connection.

Caution: The plugin is not designed to be run in multi-threaded, multi-process or auto-replicate environments.

It has not been designed for parallellization in regards to internal resource usage, file and data access, or logged-on users.

Output

The output of this task is the unchanged Job File.

Task properties

Connection tab

The Connection tab fields set the connection parameters. You can use static text and/or Workflow variables, data and lookup functions.

Right-clicking a field opens a context menu that supports adding variables, data and lookup functions (see Data selections), where available.

  • DocuWare Server: Enter the DocuWare Host address. For example https://mycompany.docuware.cloud

  • Organization: Enter registered Organization name. For example MyCompany

  • Platform: Enter the DocuWare platform. For example docuware/platform

  • Authentication section:

    • Basic/OAuth2 radio button: Select either the Basic cookie based authentication (not recommended), or the newer OAuth 2 protocol for authorization.

      Note: The “OAuth2” authentication method is not only more secure, but the old cookie based authentication (Basic) has been turned off for cloud based systems as of DocuWare version 7.11.

      The Basic cookie based authentication will continue to work for DocuWare 'on premise' installations prior to DocuWare 7.11.

      Note: This radio button selection was added in the 2022.2.1 rel.3 version of the plugin, which was released in December 2024. It was added to cater for the DocuWare 7.11 release. Earlier versions of the plugins will not have this option present.

      To download the 2022.2.1 rel.3 version of the plugin (or later), please free to download it from the Resource Center (https://olresourcecenter.uplandsoftware.com)

    • Username: Enter the DocuWare login Username.

    • Password: Enter the password associated with the selected DocuWare login Username.
      Use the password Hide/Show button to either display or obscure the password.
      Clicking this option will display the password.
      Clicking this option will obscure the displayed password.

      Note: When the password is set via a variable, it is important to know that the password might be visible. It is the user's responsibility to protect the passwords in such cases.

  • Test Connection: This button tests the connection details entered in the Connections tab. If a successful connection is made, then Connection Success will appear as the current status.

    When a successful connection is made a listing of all the available cabinets and fields for that login will be downloaded and stored locally, for use in the Upload tab. Once a connection has been established and the cabinet and file information obtained, the plugin will open upon the Upload tab when next plugin is next opened.

    As different users can have different permissions (such as access to different cabinets) this information is tied to both the host and username. If either the user or server is changed, then a new Test Connection will be required to re-populate the cabinets and fields for that new connection.

    If the Test Connection fails, information about the reasons for failure will be displayed in the status area, if the plugin can determine the reasons for the failure.

Upload tab

The Upload tab provides the controls for defining the file to be uploaded, included related index values. The plugin window is expandable, which helps to display all the information at once when field names are quite long.

File to upload

This frame holds all the elements on the file which is to be uploaded to DocuWare.
The plugin can upload either the incoming Job file, or a file from the file system (External file).

Select either:

  1. Job file: Select this option to upload the current Workflow Job file (the equivalent of using %F).

  2. External file: Select this option to upload a file from the file system. Selecting this option activates the file selection input field.
    To select a file click the Browse button () to browse for a file, or right-click within the input field to open the context menu which allows the selection of variables, data and lookup functions (see Data selections). Note that the plugin will not verify the validity of the file name, if it were not browsed for.
    If no upload file has been specified, DocuWare will take the name of the uploaded file as the document name. If the Workflow Job File is to be uploaded, it is highly recommended renaming the file, as otherwise the Workflow temporary file name will become the document name.

  • File type: Enter the type of file, from the list contained in the drop down box. Select Auto-detect if unsure of the file type, and the plugin will then set the content-type based upon the file extension.
    The File type entry is directly editable so your can enter your own file type, should it be missing from the list.

Destination

In order to upload a file the plugin needs to know to which File Cabinet it must be directed to. The details for this are all contained in this Destination frame.

  • File Cabinet: You can select a File Cabinet from the drop-down list if the Test Connection was run successfully. The plugin will have a list of available File Cabinets, extracted from the DocuWare server.
    Alternatively, you can enter the File Cabinet entry directly. You may also use variables, data and lookup functions. Right-clicking within the field opens the contextual menu. See Data selections, to assist with this.
    If the File Cabinet specified in the text box does not exist at run time, the plugin will replace it with the first File Cabinet name on the previously extracted Cabinet list.
    The File Cabinet entry is case-sensitive.

    Note: Each cabinet has a default document name, which is configured in the DocuWare preferences.
    The current document name will be highlighted in the read only Document name field screen entry, whenever a new Cabinet is selected.

  • Create a new document / Update existing document selection: Choose between these two options.
    Each does as the name suggests.

    • Create a new document will load the document as a new document to the DocuWare server.
      This document will be named based upon the document name field (as seen highlighted in the Document name field screen entry).
    • Update existing document will add to an existing document of the same name on the DocuWare server, based upon the following criteria:
      • Search Field. Enter the Field to search on.
        This can be entered directly as static text, or you could use the Field picker () to launch a Field selection pick list that is populated with all the available fields, and them select the desired field from there.

        Note: The pick list display can be customized by entering a search string in the entry field atop the Field Picker box. This restricts the listed fields to just those containing the search string.

      • Value. Add the value to apply.
        You can use static text and/or Workflow variables, data and lookup functions. Right-clicking in the field opens the contextual menu that allows adding variables, data and lookup functions (see Data selections).

      Note: If more than one document is found based upon the selected search criteria, the update will fail.


Index Data

Select whatever Index fields you want to add via this index table.

  • You can populate the table with all the available Index Field options at any time by selecting the Add missing fields () button. If selected initially this will add all the available fields to the table. If selected after some fields had already been added via the field picker button (), it will add any missing fields to the end of the Index data table.

  • You can Add () or Remove () individual entries, as well as move them up () or down () within the table.

  • At any point you can verify the accuracy of the selected Index options by selecting the Validate () button.

  • Index entries that are duplicated appear in orange text, and index entries that do not match available options appear in red.

Note: The Document name field entry will appear in italics in the table.

All index values must be entered in a unified format. This means as follows:

  • Strings: String values will be uploaded to Docuware "as-is", without modifications.
    Strings are Unicode-aware, so that non-ASCII characters can be entered as well, like Chinese, Japanese, etc..

  • Numeric values: Numeric values must be entered using only digits 0-9, a preceding - or + sign and the dot as decimal separator. Any other characters are prohibited and using them will lead to an error. The plugin will convert the value internally to match the respective numerical format as defined inside DocuWare.

  • Date values Any date values must be entered in unified UTC format. Generally allowed formats are:

    • yyyy-mm-dd

    • yyyy-mm-dd HH:MM:SS

  • Yes/No, True/False, 0/1 values: Such values may be entered as either "Yes", "1", "True" or "No", "0", "False". Any other value will raise an error.

Also note that index names are case-sensitive.

Note:  Fields with empty values will not be saved when the OK button is pressed.

Response

Specify an optional Workflow variable that is used to store the result.

The DocuWare plugin searches for the variable by name and sets the JSON response into the variable.

So using dwresponse as the variable name would mean that DocuWare Upload searches for the local variable of that name.