URL Integration parameter

URL Integration in DocuWare enables access to archived documents and DocuWare functions directly via web links. This article provides an overview of the available parameters that can be used to customize and control URL integrations in DocuWare.

URL structure

The URL used to access parts of the DocuWare Web Client from other applications always includes the base URL along with additional parameters, as explained below.

Click here for more code examples and NuGet packeges.

Base URL

The base URL for the integration is made up of the components "HTTP address for the Web Client" and the suffix "integration".

Address of the associated Web Client

The HTTP address of a Web client is made up of the server name of the computer on which the platform was installed, plus the IIS (Internet Information Services) target directory in which the DocuWare Platform Service was published.

• http://<your_servername>/<DocuWare>/<Platform>/WebClient

You find the address in DocuWare Administration on system level in the Web Connections settings.

Default path extension

Add the suffix "integration" to the URL.

• http://<your_servername>/<DocuWare>/<Platform>/WebClient/Integration

With DocuWare version 7.1 customers of DocuWare Cloud can create an integration URL without any organisation GUID or specifying name, because the organization is encoded in the base address of the URL. The same applies for users of DocuWare on-premises when the system has only one organization.

Only when a DocuWare system has more than one organization, an identifier is needed:

• http://<your_servername>/<DocuWare>/<Platform>/WebClient/OrgGUID/Integration

Table URL Parameter

The parameters are added at the end of the base URL. The data part of the URL containing the parameters starts with a question mark (?).

The following table provides a summary of possible parameters. Information about encryption and Base64-encoding you will find in the following chapters.

The parameters must be written with lower-case letters. Exception: by contrast, the values for the p parameter (e.g. V for Viewer integration) must be written in upper case.
The ep, ns, vf, vu parameters are only used in the case of encryption (see section Automatic Login to Web Client via URL).

Base64 URL Encoding

Values must be encoded for the "lc" and "q" URL parameters, since complex data must be encoded before it can be used in a valid URL. DocuWare uses base64 URL encoding. Since the characters "+" and "/" may not be used in a URL, they must be converted to "-" and "_". You can find detailed specifications for this in the RFC 4648 document, section 5 (http://tools.ietf.org/html/rfc4648#section-5).

By way of example, the code in PHP looks like this:

 function base64url_encode($plainText)
    {
        $base64 = base64_encode($plainText);
        $base64url = strtr($base64, '+/', '-_');
        return ($base64url);   
    }

Please note with strings containing inverted commas (see section Examples, e.g. [COMPANY]="Peters Engineering") that the inverted commas can vary depending on which editor you are using and can therefore also have different Base64 encoding. This will not affect the functioning of the URL.

In addition DocuWare removes the trailing ‘=’ characters and adds 0, 1 or 2 depending on characters removed. Implementation uses the .NET function "HttpServerUtility.UrlTokenEncode", find more information on the Microsoft website.

Parameter: further information

Encoded DocuWare login details

The login must consist of a UTF-8 character string encoded as Base64 URL. The unencoded character string looks like this:

User=<username>\nPwd=<password> (\n indicates a new line)

If you want to encode the user login as administrator and the password as admin, you enter it like this:

User=administrator\nPwd=admin

You encode this string. The result is:

VXNlcj1hZG1pbmlzdHJhdG9yXG5Qd2Q9YWRtaW4=.

This is the value you use for the "lc" parameter.

Query Parameter

The query must consist of a UTF-8 character string encoded as Base64 URL.

The unencoded character string looks like this:

[Name of a field in the database]<any number of WhiteSpaces><relational operator><any number of WhiteSpaces>"<search criteria for the field type of DocuWare field>"

e.g.

[COMPANY]="Peters Engineering"

[CONTACT] LIKE „Wi*"

Please note that the field names must be identical to their names in the database; note too that they are case-sensitive.

If the query contains numerals, the query works in the same way as for letters, e.g.

[RECORDNUMBER]="12345"

For a decimal set a period or a comma as separator e.g. "123,45".

If the query contains a date query, the date information must be entered in a non-language specific format, "YYYY-MM-DD", so that the query will always work correctly. For a date with time use the format YYYY-MM-DD HH:mm:ss.

If the query contains one or more quotation marks, a backslash must be placed in front of the quotation mark, in order to remove the meta-meaning of the quotation marks. Example:

[SUBJECT]="So-called \"Web 2.0\""

Possible relational operators are:

<=, >=, <, >, = and LIKE; where LIKE is only valid for text fields. If the LIKE operator is used, the search criterion must contain at least one * (asterisk).

Simple search expressions can be combined into more complex search queries using logical operators, e.g.:

[COMPANY]="Peters Engineering" AND [STATUS]="Valid"

Possible logical operators are:

AND, OR, NOT.

Note that there must always be at least one space before and after each logical operator. This also applies to the LIKE operator.

Encode each valid search query with Base64 encoding. Example [COMPANY]="Peters Engineering" then becomes:

WW0NPTVBBTlldPSJQZXRlcnMgRW5naW5lZXJpbmci.

Query with numeric fields

Please enter decimal points if you use decimal values in numeric fields. With a decimal point the query is culture independent an can be used with different culture settings.

Parameter “dv”

With the dv parameter you can specify individual or several field values for an integration of the search dialog, result list and viewer (SLRV) types. This means that these fields in the search dialog are already filled in. The user can delete or change these field entries if necessary.

Nomenclature

The whole string must be Base64 URL-encoded. The field values must be in the following format:

"[FieldName1]=fieldValue1&[FieldName2]=fieldValue2"

The database name of the field should be entered as the field name.

Example: "[COMPANY]=Peters Engineering&[CONTACT]=SANDERS"

In a numeric or data field, if one of the "From" or "To" fields - or both - are to be filled in, these fields are separated with ;.

Examples:

[NUMERIC_FIELD]=1;5 both "from" and "to" are also filled in

[NUMERIC_FIELD]=;5 only fills the "to" value

[NUMERIC_FIELD]=1 only fills the "from" value

In KEYWORD fields, a list is required where entries are also separated with a semicolon ;.

If the dv parameter defines a date query, the date information must be entered in a non-language specific format, "YYYY-MM-DD", so that the query will always work correctly.