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
List of all URL parameters
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.
All of the following parameters in encrypted form. The passphrase must be defined in DocuWare Administration.
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).
bid parameter
Description: ID of the document tray
Required
Encrypted: When you want to understand the value, then it has to be decrypted.
did parameter
Description: Doc ID
Required
if no query (via task list or parameter) and no search dialog is defined;
useful if you want to display a specific document;
Required if DH (document history) is selected as an integration. Then the DocID denotes the document for which all versions are to be shown.
Annotation: You may use all DocIDs of the file cabinet or the GUID of the result list in the URL.
displayOnDoc parameter
Description: shows the document directly in the case of a unique hit
Annotation: If only one document is found, this is shown directly in the Viewer in a DH integration or RL instead of in a list first.
displayOnDoc parameter
Description: shows the document directly in the case of a unique hit
Annotation: If only one document is found, this is shown directly in the Viewer in a DH integration or RL instead of in a list first.
Encrypted: When you want to understand the value, then it has to be decrypted.
docLink parameter
Description: ID of the document relation
Required for the document type document link
Encrypted: When you want to understand the value, then it has to be decrypted.
dt parameter
Description: Download type
Required: Not required: If "D" is defined for the integration, "plugin" will be used by default as the download type; only required if "Download" should be defined as the type
Encrypted: When you want to understand the value, then it has to be decrypted.
dv parameter
Description: specifies field values for Search dialog, Result List and Viewer (SRLV)
Annotation: In a search dialog, specify certain field entries so that the search is already partly predefined.
Encrypted: When you want to understand the value, then it has to be decrypted.
ep parameter
Description: encrypted parameter
Required: can only be used in combination with an integration type (p)
Permitted values / annotations: All of the following parameters in encrypted form. The passphrase must be defined in DocuWare Administration.
Base64 URL encoded: When you want to understand the value, then it has to be decoded.
fc parameter
Description: file cabinet
lc parameter
Description: DocuWare login
Required: no
Annotation: All existing DocuWare user logins; login must be Base64 URL-encoded
Base64 URL encoded: When you want to understand the value, then it has to be decoded.
Encrypted: When you want to understand the value, then it has to be decrypted.
lct parameter
Description: Token for DocuWare login
Required: no
Annotations: If a login credential token is stored on the Authentication Server, the user can log in to Web Client with a GUID; entering a password is not required.
A login credential token can be generated by using DocuWare Platform Service and must be encrypted
Base64 URL encoded: When you want to understand the value, then it has to be decoded.
Encrypted: When you want to understand the value, then it has to be decrypted.
ns parameter
Description: noise
Required: no
Permitted values / annotations: Ensures that the result of the encryption is never the same, i.e. the cipher text is always different. To ensure this, noise should always be inserted at the beginning of the parameter string.
Encrypted: When you want to understand the value, then it has to be decrypted.
p parameter
Description: Elements to be integrated:
V = Viewer only
RLV = result list and Viewer
D = Download (Plugin)
SRLV = Search dialog, Result List and Viewer.
A search dialog must be defined in the URL
The results of a fulltext search will not be highlighted with colour in the DocuWare viewer.DH = Version history (document history)
DH requires the Enable version management option enabled for the file cabinet in which the referred documents are locatedIND = Index Dialog (Info Dialog)
WFTL = Workflow Task List
WFST = Workflow Single Task
SWT = Send Request (Simple Workflow Task)
SWO = Sent Requests (Simple Workflow Owner)
B = document tray
DL = Document Relation (document link)
Required
Annotations:
For WFTL, WFST, SWT and SWO the module Workflow Manager is required.
A result list with a folder structure is not supported
Encrypted: When you want to understand the value, then it has to be decrypted.
q parameter
Description: Query
Required: Only required if no search dialog is defined in the URL
Annotation: Possibile are any valid queries in UTF-8 format.
Queries must be Base64 URL-encoded.For searching in fulltext mode, the "DocuWare Fulltext" field name must be used, e.g. [DocuWareFulltext] LIKE "*EINSTEIN*"
Base64 URL encoded: When you want to understand the value, then it has to be decoded.
Encrypted: When you want to understand the value, then it has to be decrypted.
rl parameter
Description: result list
Required: Only required if no search dialog is defined in the URL and for the integration of an index dialog.
Encrypted: When you want to understand the value, then it has to be decrypted.
sed parameter
Description: search dialog
Required: Required if users are to be given the option to run searches; in which case the query will not be defined in the definition of a task list or by a parameter in the URL
Annotations: Keep in mind that the user utilizing this search dialog needs access to this dialog
Encrypted: When you want to understand the value, then it has to be decrypted.
vf parameter
Description: Valid from
Define a validity period for the URL with the parameters vf + vu (see below). Both parameters can be set individually or together; if e.g. only ‘vf’ is set, the URL will never expire after the ‘vf' date
Annotations: Format in accordance with ISO 8601: "yyyy-MM-ddThh:mm:ss.fffffffzz"
"yyyy" = year
"MM" = month
"DD" = day
"hh" = hour
"mm" = minutes
"ss" = seconds
"fffffff" = fractions of a second
"zz" = time zone or UTC offset (e.g. "Z" for GMT, "+01" for Berlin)
Any part can be left out, working from right to left. If "zz" is missing, local time will be used.
yyyy-MM-dd defines a date without a time.
:,T,-,. are merely separators
Encrypted: When you want to understand the value, then it has to be decrypted.
vu parameter
Description: Valid to
Define a validity period for the URL with the parameters vf + vu (see below). Both parameters can be set individually or together; if e.g. only ‘vf’ is set, the URL will never expire after the ‘vf' date
Annotations: Format in accordance with ISO 8601: "yyyy-MM-ddThh:mm:ss.fffffffzz"
"yyyy" = year
"MM" = month
"DD" = day
"hh" = hour
"mm" = minutes
"ss" = seconds
"fffffff" = fractions of a second
"zz" = time zone or UTC offset (e.g. "Z" for GMT, "+01" for Berlin)
Any part can be left out, working from right to left. If "zz" is missing, local time will be used.
yyyy-MM-dd defines a date without a time.
:,T,-,. are merely separators
Encrypted: When you want to understand the value, then it has to be decrypted.
waitDocContent parameter
Description: Wait for document content
Required: no, default value is "true"
Annotation: For "index dialog with viewer": With "true" a database record is stored not until before it is assigned to a document. With "false" the database record is stored as soon as it is created. The document can be added later.
wiid parameter
Description: Workflow instance ID
Required if when the integration type Workflow task is selected
Encrypted: When you want to understand the value, then it has to be decrypted.
wid parameter
Description: Workflow ID
Required: yes for integration type Workflow Task or Workflow Task List
Encrypted: When you want to understand the value, then it has to be decrypted.
wr parameter
Description: Workflow role
d = designer
c = controller
Required for Workflow Task List
Encrypted: When you want to understand the value, then it has to be decrypted.
wtid parameter
Description: Workflow task ID
Required: Required for integration type "Send Request"
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.