Create URL Integration manually

URL Structure

The URL with which parts of DocuWare Web Client are called from other applications always consists of the base URL plus additional parameters, which is eplained below.

Click here for even 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.

Encoded DocuWare Login

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 Parameters

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: Details

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.

Examples

You can try out all the examples listed here in your DocuWare installation. All you need is to have installed the sample file cabinet and published the Platfom Service in the IIS default site. You must enter the real server name. All other parameters (e.g. GUIDs) must match the values in your installation.

All URLs of the following sample addresses start with

• http://<your_servername>/Docuware/WebClient/Integration

Precondition for the example URLs in this section is, that the user as the right to access the search dialogs, result and task lists, please see also chapter "Specify rights".

Examples Login-Parameter

A result list &p=RLV&rl=<result list id> shall be called up

with manual login

• http://<your_servername>/DocuWare/Platform/WebClient/Integration?p=RLV&rl=<result list id>

The user has to enter the credentials, before the result list is shown.

with single sign-on

The parameter for the Windows login is "SSO". It is added in the base URL before the org-ID:

• http://<your_servername>/DocuWare/Platform/WebClient/SSO/Integration?p=RLV&rl=<result list id>

automatically with DocuWare login

It is possible to include the DocuWare credentials in the integration URL. The credentials have to be BASE64-encoded and encrypted.

Logindaten: User=administrator\nPwd=admin

Logindaten Bbse64- encoded: VXNlcj1hZG1pbmlzdHJhdG9yXG5Qd2Q9YWRtaW4=

This string is added to the URL with "lc"

• http://<your_servername>/<DocuWare>/<Platform>/WebClient/Integration?&p=RLV&rl=<result list id>&lc=VXNlcj1hZG1pbmlzdHJhdG9yXG5Qd2Q9YWRtaW4=

If the credentials are included in the URL, DocuWare only accepts an encrypted URL. If you use individual, fixed URLs, you can encrypt and decrypt them using the DocuWare URL Creator (see section DocuWare URL Creator). If you encrypt the encryptable parameters yourself, because the URLs need to be generated "on the fly", you can use either GAPI or the encryption algorithms in section Encryption Algorithms.

The encrypted URL is added with the parameter "ep":

• http://<your_servername>/<DocuWare>/<Platform>/WebClient/Integration?&ep=<encrypted parameters>

Unencrypted URLs with the login parameters lc or lct can no longer be used from DocuWare Version 7.1.

To update existing integration URLs, proceed as follows:

• In the URL Creator, select "Parse URL" in the first step.

• Copy the URL into the text field and click "Next".

• Activate "Use passphrase" and enter the passphrase. You find the passphrase in DocuWare Administration in the organization area under "General".

• Click "Next" to the Summary page and copy the new URL with the securely encrypted login.

When an application generates your URL, you must customize it with the passphrase from DocuWare Administration.

Examples: Integration Elements

Integration of Viewer only, no result list, specific document is opened

DocID of the specific document is "8"

• &p=V&rl=a60d2279-227d-454b-815c-14d64eb165a1&did=8

If you do not enter a DocID here, the first result in the result list is automatically displayed. In addition, a query can be defined in the URL.

• &p=V&rl=69e807b6-70e8-48c2-8857-2864dfebc4ac

Integration of Viewer and result list

• &p=RLV&rl=69e807b6-70e8-48c2-8857-2864dfebc4ac

The result list defined by GUID in this URL must be a task or result list.

Integration of search dialog and Viewer and result list

• &p=SRLV&sed=0c825e8b-e21f-48e8-b31f-590bf60a6c59

There are no parameters to be defined for a result list here, because a search dialog is opened. Every search dialog always has a result list assigned to it.

Download integration

• &p=D&rl=a60d2279-227d-454b-815c-14d64eb165a1&did=8

This URL opens the document in the plugin program, because "Download" has not been explicitly defined as the download type. If you want a document to be proposed for downloading, the URL is:

• &p=D&rl=a60d2279-227d-454b-815c-14d64eb165a1&did=8&dt=Download

You can also define a task list or a query for a download integration. If more than one result is returned, the first result is always displayed in the plugin program or proposed for downloading.

Naturally, for all the examples in this section the login can be defined as a parameter; as an alternative to the task list you can also define the query as a parameter.

Examples of Queries in the URL

None of the following examples have a file cabinet or a result list defined in DocuWare Administration. Access is via user login in the URL; user name is guest and the password is also guest. Only the parameters of the URL are listed here. The base URL is same as before.

If you define a query in the URL and the result list is a task list, the parameter q" can refine the query of the task list.

Queries with simple search expression

[COMPANY]="Peters Engineering"

• &p=RLV&lc=VXNlcj1ndWVzdFxuUHdkPWd1ZXN0&rl=a60d2279-227d-454b-815c-14d64eb165a1&q=W0NPTVBBTlldPSJQZXRlcnMgRW5naW5lZXJpbmci

[CONTACT] LIKE "Lau*"

• &p=RLV&lc=VXNlcj1ndWVzdFxuUHdkPWd1ZXN0&rl=a60d2279-227d-454b-815c-14d64eb165a1&q=W0NPTlRBQ1RdIExJS0Ugk0xhdSqT

Queries with complex search expressions

[COMPANY]="US-Steel" AND [DEPARTMENT]="Production"

• &p=RLV&lc=VXNlcj1ndWVzdFxuUHdkPWd1ZXN0&rl=a60d2279-227d-454b-815c-14d64eb165a1&q=W0NPTVBBTlldPZNVUy1TdGVlbJMgQU5EIFtERVBBUlRNRU5UXT2TUHJvZHVjdGlvbpM=

[COMPANY]="Phone Wizard" AND [DEPARTMENT]="Accounting" AND [STATUS]="to be approved"

&p=RLV&lc=VXNlcj1ndWVzdFxuUHdkPWd1ZXN0&rl=a60d2279-227d-454b-815c-14d64eb165a1&q=W0NPTVBBTlldPZNQaG9uZSBXaXphcmSTIEFORCBbREVQQVJUTUVOVF09k0FjY291bnRpbmeTIEFORCBbU1RBVFVTXT2UdG8gYmUgYXBwcm92ZWSU

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.

Example Index Dialog

An info dialog can be integrated with the following URL-scheme:

• ? p=IND&rl=<Resultlist_ID>&fc=<FileCabinet_ID>&did=<doc_ID>

IND = parameter for index dialog (info dialog)

rl = ID of the result list

fc = ID of the file cabinet

did = ID of the document related to the info dialog

IDs of the elements of DocuWare

All parameters have to be encrypted.

Example: Document Tray

A document tray integration provides the user with the complete functionality of a a document tray in the Web Client.

A tray can be embedded with this URL-scheme:

• ? p=B&bid=<Basket_ID>

B = parameter for document tray

bid = ID of the document tray

Learn how to find the IDs of the elements of DocuWare

All parameters have to be encrypted.

Example: Document link

To integrate the link to a document you can use this URL scheme:

• ?p=DL&fc=<FileCabinet_ID>&did=<doc_ID>&docLink=<doc_ID>

DL = parameter for integration type "document link"

fc = ID of the source file cabinet. This is the file cabinet which contains the link.

did = ID of the document related to the link

docLink = ID of the document link

IDs of the DocuWare elements

Encryption

If you use individual, fixed URLs, you can encrypt and decrypt them using the DocuWare URL Creator (see section DocuWare URL Creator). If you encrypt the encryptable parameters yourself, because the URLs need to be generated "on the fly", you can use either GAPI or the encryption algorithms in section Encryption Algorithms.

Encryption Algorithm

Please note that some parameters need to be base64URL-coded for the encryption. For more information, refer to section URL Parameters.

URL Encryption

This uses a symmetric encryption algorithm.

Advanced Encryption Standard (AES) in accordance with specification FIPS-197 is used for the encryption, with the following parameters:

• Block Size = 128 Bits

• Cipher size = CBC (Cipher Block Chaining)

• Initialization vector (IV) = 128 bits

• Key length = 256 bits

• No salt

Keys

An AES key with 256 bits and an initialization vector (IV) with 128 bits are used for encryption/decryption. The key and the initialization vector must also be known to the external application. Passphrases are used for this. DocuWare uses this passphrase to calculate the key and the initialization vector. The passphrase is encrypted and stored as a property in the settings of the Web integration. The administrator must also enter and encrypt the passphrase in the external application.

The following algorithm is used to ascertain the AES key and the initialization vector from the passphrase:

• Ascertaining an SHA-512 hash from the passphrase (result 512 bits). This can be implemented in .NET using the SHA512Managed-class and is also supported by Java and PHP. Third-party add-ons are available for JavaScript.

• Use the first 256 bits (32-bytes array) for the AES key.

• Use the following 128 bits (16-bytes-array) for the initialization vector.