When working within your organization, users typically work with some kind of application that is specific to your branch and in which users work for the most part of their day.
With the integration of Xtendis in your organization, such applications can be customized so that it is possible for users to access documents or dossiers in Xtendis from within that external application.
Example: In an application for processing orders, documents such as invoices or mailings for a customer that are stored in Xtendis can be looked up.
Such an integration works by adding a URL in the form of a button or link that users can click to access one or more documents or dossiers in Xtendis. This makes working with the daily application in combination with Xtendis much more efficient because users do not have to manually access Xtendis and search for the documents or dossiers themselves.
How it works
The URL is a query which is generated using the Lookup tester page in the Functional management section of Xtendis.
Example: https://my-xtendis.nl/web/weblauncher.aspx?archiefnaam=Central&doc_Document%20date=13-03-2023
The result can be a single document or dossier, or multiple documents or dossiers.
Because users are given access to Xtendis, they needs to exist as a user in Xtendis and have sufficient access rights to view the documents or dossiers.
Users can be given the following type of access:
- Full access, similar to opening Xtendis and manually searching for the documents or dossiers. This is done through the so-called 'Web launcher'.
- Limited access, providing basic functions such as printing and downloading the documents. This is done through the so-called 'Web lookup'.
Authentication of the user proceeds in the same way as for the regular Web application.
Example: Windows Authentication for the Web application also means Windows Authentication for the Web lookup; ADFS linking for the Web interface also means ADFS for the Web lookup.
The use of the Web launcher requires the access right to use the Web (the right to use the standard web application).
The use of the Web lookup requires the access right 'lookup use'.
Note: If you are using a workflow on documents (using flow buttons) in combination with the Web lookup, the Web launcher should be used. This is because the flow buttons are not part of the basic functions available with the Web lookup.
Basic setup
The so-called 'endpoint' of the URL determines the search method and is therefore an important part of the setup.
The following endpoints are available:
- For the Web launcher: weblauncher.aspx?
- For the Web lookup: weblookup.aspx?
The logic of a query string is the same in both the Web lookup and the Web launcher. The following are important:
- The archive in which the search needs to be performed.
Example: archivename=General Archive
- At least one search criterion should be included.
Example: &invoicenumber=2018004
These search criteria can be properties of the document and / or the dossier. In addition, searching can be done on numerous technical properties.
To help constructing the query, the Lookup tester in the Functional management section of Xtendis can be used. See Constructing the query below.
Note: A property can only be mentioned once in the lookup.
Accessing the page
To access the page, access the Functional management section of Xtendis and in the menu on the left, click Lookup tester.
Constructing the query
The Lookup tester page makes it easy to construct the query. It contains various components that are used from top to bottom.
| # | Component | Description |
|---|---|---|
| 1 | Archive list | A list of available archives in the system. |
| 2 | Access type list | Choose between Web launcher and Web lookup. |
| 3 | Search string | The part of the URL that defines what to search for. |
| 4 | Copy button | Copies the full URL to the clipboard. |
| 5 | Show number of found documents | When enabled, shows the number of documents that are currently found by the query. |
| 6 | Tabs |
Search fields. Shows a list of available properties to include. Summary. Shows a summary of the search, either as text or as a visual representation. Special characters. Contains fields for encoding special character into code. Example: entering @ results in %40. |
| 7 | Filter | Filter for filtering the list of properties. |
| 8 | Properties |
The available properties to include. Icons in front of the property indicate whether the value is text, numeric, or a date. Values that contain a list of fixed values show an info icon. Click the icon to view the list. |
Step 1. From the archive list, choose the archive in which should be searched.
Step 2. From the access type list, choose either the Web launcher or the Web lookup.
Step 4. (Optional) Enable the option Show number of found documents to see the number of documents that the query finds.
Step 4. In the list of properties, click the plus-sign in front of the property that you want to include. Click it again to remove it.
Tip: Use the filter to reduce the number of properties that are shown by either choosing a category from the list and / or by typing (part of) the name.
Note: See the section Advanced setup below for more powerful settings such as using date ranges, multiple values, and more.
Step 5. (Optional) Select the Summary tab to view a summary of the query either as text or as a visual representation.
Step 6. (Optional) In case a special character needs to be included such as an %-sign or an accented character, access the Special characters tab and enter the character in one of the fields. The encoding is displayed next to the field.
Step 7. Click the Copy link button to copy the URL to the clipboard.
Step 8. Test the link by pasting it in a Web browser to see if it gives the desired results.
Advanced setup
Apart from using the tools provided on the page, the query can be enhanced by using advanced options such as date ranges, multiple values, and more. These are explained below.
Archive definition
For the archive definition, you can refer to the archivename or alternatively the archiveid.
OR statements
An OR statement can be constructed by referring to multiple values separated by a semicolon.
|
Example: Here, a search is done in the archive 'WoodWing archive' for documents that refer to the organization 'WoodWing' OR 'Expansion': archivename=WoodWing+archive&organisation=WoodWing;Expansion |
Date format
Date fields are always constructed in the following format: dd-mm-yyyy.
Date range
Date ranges can be constructed by including the letter t.
| Range | Description | Example |
|---|---|---|
| From | Add the date followed by a t. | Documentdate=01-12-1988t |
| Until | Add a t followed by the date. | Documentdate=t03-07-2018 |
| From-until | Add the from date, followed by a t, followed by the until date. | Documentdate=01-12-1988t03-07-2018 |
Decimal format
Decimals in numeric values are represented by a decimal point.
Example: 506.60.
Numeric ranges
Numeric ranges can be constructed by including the letter t.
| Range | Description | Example |
|---|---|---|
| From | Add the value followed by a t. | Amount=700t |
| Until | Add a t followed by the value. | Amount=t1200.50 |
| From-until | Add the from value, followed by a t, followed by the until value. | Amount=60.003t1200.340 |
Multiple value fields
Multiple values within the same field can be referenced by separating them by a semicolon.
Example: &tags=ProcessorAgreement;Planning
Note: This only applies to fields designated as multiple in the archive definition.
Showing search fields when only one result is found
Info: This only applies to using the Web launcher.
When only one result is found, the default behavior is that only the item is shown without any options to search further.
When needed, the search options can be included in this scenario by adding &showAll=1 to the query.
Example:
https://my.xtendis.nl/web/weblauncher.aspx?archiefnaam=Central&t_INDEXEERDATUM=21-02-2023&showAll=1.
Showing only the latest active document
Info: This feature requires Xtendis 7.3.12 or higher (see how to check which version of Xtendis you are using).
To point the user towards the latest active document, use &showall=false.
This shows a viewer with only the active document, instead of a complex user interface with all documents.
Special characters
Document properties and values must be URL-safe, meaning that they must not contain any characters that could mean something else in a URL.
Examples include the ampersand, the hash, and the dot (&, #, and .).
To be able to use these in the URL , they must be 'URL-encoded'.
The correct way of encoding can be found on the Internet. Some sources to use are:
- Percent-encoding on mozilla.org
- The HTML URL Encoding Reference on w3schools.com
- URL Encoding on blooberry.com
The Lookup tester mentioned earlier can also help with finding the correct encoding.
Document properties versus dossier properties
When the same characteristics appear in the references for both the document and the dossier, then it is wise to give the properties a prefix.
Use doc_ for document characteristics and dsr_ for dossier characteristics.
|
Example: Here, the 'reference' property is used in both documents and dossiers and is therefore prefixed: https://my.xtendis.nl/web/weblauncher.aspx?archiefnaam=Central&t_INDEXEERDATUM=21-02-2023&doc_reference=2018007&dsr_reference=dar_2018003 |
Searching for dossiers
When searching for dossiers, the query string should only be extended by using 'launch=dsr' .
This gives the user a list of dossiers in which they open each one.
Document properties cannot be used for searching for dossiers.
Functions available in the Web lookup
The functions available in the Web lookup are limited. They can be supplemented if necessary by changing the WeblookupEditionType option between Simple and Full in the Xtendis Cockpit under General Settings.
Note: If the Full option is needed, it is better to switch from Web lookup to Web launcher.
No results
When the query is executed, it may happen that no results are displayed and that a message appears that the search was incorrect.
Such instances are reported in the log files from where it can be analyzed if something went wrong with the translation of the URL to a query.
The following are some common problems:
- The archiveId or the archive name is not correct (the archive IDs might differ between test and production).
- There is a space before or after the archive name.
- The document or dossier property is misspelled.
- Searches must have at least one property.
- The URL contains a special character.
Wildcards
The percentage character can be used as a wild card for 'starts with', 'contains', or 'ends with' constructions.
As it is a special character, is should be encoded as %25.
The following table contains some examples:
| Example | Description |
|---|---|
| STATUS=%25error | STATUS ends with 'error'. |
| Subject=renovation%25 | Subject starts with 'renovation'. |
| Subject=%25renovation%25 | Subject contains 'renovation'. |
| Title=project%25plan | Title starts with 'project' and ends with 'plan'. |
Comments
0 comments