Posted Fri, 13 Sep 2019 11:43:16 GMT by Aurelien BRUNARD

Hi all,

I'm looking for help to invoke a Docuware REST API method named « queryDocuments » to perform document searches by fields


The service signature is :

/DocuWare/PlatformRO/FileCabinets/{fileCabinetId}/Query/Documents?q={q}&fields={fields}&sortOrder={sortOrder}&start={start}&count={count}&format={format}&additionalCabinets={additionalCabinets}&csvDelimiter={csvDelimiter}&csvIsUtc={csvIsUtc}&includeSuggestions={includeSuggestions}

What is the format of the {q} parameter during a GET call ?

What is the description of the "ResultSet Query" object during a POST call ?

Would anyone have an example of using this method ? The documentation is really very poor :(

Thanks

Posted Fri, 13 Sep 2019 14:30:18 GMT by Joe Kaufman Manager
Aurelien,

If the "q" is like the "q" parameter for URL integration, here is what I have in my comments about how to form the query parameter:
 
Field names in queries are case sensitive! Field names (in the database) are usually ALL CAPS.
The actual database field name of a field can be viewed in the DocuWare Administration desktop
application. Queries place field name in square brackets and the value on double-quotes.
Though, for numeric fields, the quotes appear to be optional. Operators can have whitespace
around them. Here are example query expressions:

[DWDOCID]=123    (This will query by the internal DocuWare document ID.)
[CUST_NO] = "WA60"    (This will query the field "CUST_NO", trying to exactly match "WA60".)
[LASTNAME] LIKE "K*"    (Wildcard search -- note use of "*" instead of "%" for wildcard character.)
[SHIPTO_STATE] = EMPTY()    (Queries SHIPTO_STATE for empty values ("EMPTY()" must be uppercase).)
[BILLTO_STATE] = NOTEMPTY()    (Queries BILLTO_STATE for non-empty values ("NONEMPTY()" must be uppercase).)
[DocuWareFulltext] = "find this string"        (Full-text search.)
[DWSTOREDATETIME] > 2017-06-14 19:45:31        (Date/time expression *** CONVERT TO UTC ***)
[START_DATE] >= 2016-06-01 AND [START_DATE] <= 2016-08-01    (Boolean conditional, checking date field over a date range, inclusively.)

Expressions can be joined by AND or OR and can be qualified with NOT. Delimiters around string
values MUST be double-quotes. Also, the conditional statements and compound keywords (e.g. LIKE, AND, OR, etc.)
need to be capitalized as well.

*** SPECIAL NOTE WHEN USING DATE/TIME FIELDS ***  Date/time fields are stored in DocuWare as UTC timestamps.
While queries in the web client or Platform SDK allow the use of local date/time formats, URL Integration
queries appear to use the date/times passed in as-is and compare against the stored UTC timestamps.
So, if you are using date/time fields in your query, the date/time values need to be converted to UTC
to get accurate results.

Additionally, the query parameter needs to be URL encoded, doing whatever something like System.Web.HttpServerUtility.UrlTokenEncode() does in .NET. Not sure how I figured that out, but that's what the code (that works) says.

When it comes to the call itself, I don't use the resource you list. In fact, I think I tried it in version 6.11 and it didn't work. All I could do with that resource was to return ALL documents from the file cabinet. If I tried to add a query parameter, the call threw a strange error (in .NET).

So, I use the following resource, and it works from Visual FoxPro:
 
/DocuWare/Platform/FileCabinets/{cab GUID}/Query/DialogExpression?dialogId={dialog GUID}&count=2100000000

This works through a dialog, so it is a bit more of a pain to use since you have to know the GUID of the file cabinet and the search dialog.

Where is the query, you might ask? When using the above resource, you do it as a POST, not a GET, and the query is in the POST data. Here is an example of POSTed XML:
 
<?xml version="1.0" encoding="utf-8"?>
<DialogExpression xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"  Operation="And"  xmlns="http://dev.docuware.com/schema/public/services/platform">
    <Condition DBName="COMPANY">
        <Value>bell</Value>
    </Condition>
</DialogExpression>

You basically just construct XML with field names and values, and the values can be wildcards or system keywords like EMPTY() and NOTEMPTY(). POST this content to the resource and you get back an XML result with all the found document records. You'll have to parse that out however you see fit into whatever result you need.

Lots of trial and error on this stuff. One way to learn about what is going on under the hood is to do operations in C#/.NET using the libraries that make such operations easier to construct (syntactically). Then, if you watch network traffic with something like Fiddler you can see what the raw HTTP calls look like (I can, anyway, as our server is HTTP, not HTTPS -- not sure what happens with HTTPS). IIRC, posted data in those calls is usually JSON instead of XML, which you can totally use if you are more comfortable with JSON. I've had better luck posting XML for some reason.

Again, this is all on 6.11, an on-premise installation.

Hope this helps!

Thanks,
Joe Kaufman

 
Posted Mon, 16 Sep 2019 09:03:12 GMT by Aurelien BRUNARD

Thank you very much for your help

I managed to search for my documents with « DialodExpression » like you

I wonder if the API "queryDocuments" is really made to perform searches ...

There are no fields to specify values ​​in the POST input :(

Posted Mon, 16 Sep 2019 13:32:20 GMT by Joe Kaufman Manager
Aurelien,

I think if the query did work directly against the cabinet, it would just use an encoded "q" expression, not POST data. The problem is, it just doesn't work. I tried searching for a past thread about the error I got with GetFromDocumentsForDocumentsQueryResultAsync() when trying to use the "query" parameter, but I cannot find it anywhere (it was on the old forums). It looks like they still have not gotten it to work.

I went ahead and tried a query again to recall what the error was (on 6.11 on-premise) It is:
 
500 Internal Server Error (The given key was not present in the dictionary.)

It doesn't matter what I try for the query parameter -- if it is a non-empty string I get the above error, valid expression or not.

The count parameter does work, though, to limit the number of records returned. So, if you just want all or some the files in a file cabinet, it is the method to use so that you don't need to mess with a dialog GUID.

Thanks,
Joe Kaufman


 
Posted Tue, 17 Sep 2019 06:12:30 GMT by Aurelien BRUNARD

I do exactly the same thing as you

I encounter the same errors as you use the query parameter

The lack of reliable documentation is really detrimental to the integration of a professional software package

we are close to amateurism :(

Posted Tue, 17 Sep 2019 13:01:58 GMT by Joe Kaufman Manager
We amateurs can get a lot done if we stick together.  *smile*

On a thread long ago (trying to get the DW Platform SDK working from Visual Foxpro) I got to the point of saying I would just fill out a support ticket. Problem is, DocuWare will not give in-depth support on the Platform SDK unless you specifically license that level of support. I think it was a reasonable figure if you are doing a lot of implementing (like $1000-$1500/year), but that didn't make sense for us since we are just one installation (I am not a consultant or reseller, just a guy working for a company that had to switch migrate from Fortis to DocuWare).

When I was told I wouldn't get any help without ponying up what would have been about a 20-25% license increase for us, that's when I started using Fiddler and Postman to figure out what was going on (mainly with authentication). I also use a lot of integration with a C# wrapper program I wrote where a bunch of common functions are exposed via command line.

DocuWare may have changed their licensing scheme since them, so you could always try to ask these questions via an "official" support ticket to see what they would say (then post here, please!). In my experience, there are quite a few commercial tools out there with a powerful API obfuscated by marginal documentation and developer support that costs extra... But you can still give it a try!

Thanks,
Joe Kaufman
Posted Tue, 17 Sep 2019 15:34:05 GMT by Florian Mittermeier Manager Research & Development
Hi all,

for all developer needs please check out our new website https://developer.docuware.com.
This is a new centralized place for any information around our SDK and API.
New examples are presented there again and again.
Keep an eye on https://developer.docuware.com/News/years/2019.html to be informed about our latest changes.

@Aurelien Use the following link https://developer.docuware.com/rest/examples/postman-collection-download.html and get the Postman collection with examples for the REST API. In your case you'll find in folder Search for documents / build and use document queries the right example.

Best regards,
Florian Mittermeier
DocuWare SDK Team
 
Posted Tue, 17 Sep 2019 15:56:15 GMT by Joe Kaufman Manager

Florian,

Thanks for the input! While we have you here, can you address the original issue? I appreciate the documentation link, but the documentation is actually part of the problem in this case. Here, the "q" parameter is not mentioned or used:

https://developer.docuware.com/dotNet_CodeExamples/f9a6a984-57a9-42e9-8d26-1dd35611cf47.html?q=GetFromDocumentsForDocumentsQueryResultAsync

But this still lists "q" as a valid parameter (though it is part of an extension method):

https://developer.docuware.com/dotNet_API_Reference/PlatformServerClient/DocuWare.Platform.ServerClient.SchemaExtensions.html#DocuWare_Platform_ServerClient_SchemaExtensions_GetFromDocumentsForDocumentsQueryResultAsync_DocuWare_Platform_ServerClient_ServiceConnection_System_String_System_String_System_String___System_String___System_Nullable_System_Int32__System_Nullable_System_Int32__System_Nullable_System_Int32__System_String_System_Nullable_System_Boolean__

So, is "q" supposed to work, or not? Can you shed any light on the internal server error, "The given key was not present in the dictionary" that we both see when we try to query directly from the file cabinet? If it is broken, any plan on fixing it? It is frustrating when documentation says something should be doable but then it doesn't work.

The "Get Documents" portion of the Postman collection is not helpful either, as it only utilizes count, fields, and going after a document by specific ID in the examples. Querying for a document (directly from the file cabinet) via the "q" parameter is not illustrated. Only searching via a dialog is exemplified further down in the collection. (EDIT: Trying to use the "q" parameter in the Postman samples for directly accessing documents from the cabinet fails with the same error no matter what query expression is passed in...)

Can we get a definitive answer on the "q" parameter as used in GetFromDocumentsForDocumentsQueryResultAsync()?

Thanks,
Joe Kaufman

Posted Wed, 18 Sep 2019 15:00:36 GMT by Florian Mittermeier Manager Research & Development
Joe,

The q parameter is not official supported for external use, because of breaking changes in every release.

In order to use the document query correctly the postman example "Build the URL to use in GET request" should be used.
In the response you'll get a complete query link.
This link can then be adjusted according to your wishes except for the q parameter like in postman example "Use generated URL".

I hope the answer helps with your problem.
In the future we will improve the documentation on this point.

Best regards,
Florian Mittermeier
DocuWare SDK Team
Posted Thu, 19 Sep 2019 13:13:21 GMT by Joe Kaufman Manager
Florian,

Thank you for the definitive response!

Thanks,
Joe Kaufman

You must be signed in to post in this forum.