Zoekopdrachten maken voor het koppelen van Xtendis 7 vanuit externe applicaties

Binnen uw organisatie werken gebruikers doorgaans met een applicatie die specifiek is voor uw branche en waarin gebruikers het grootste deel van hun dag werken.

Met de integratie van Xtendis in uw organisatie kunnen zulke applicaties op maat worden gemaakt, zodat het voor gebruikers mogelijk wordt om vanuit die externe applicatie toegang te krijgen tot documenten of dossiers in Xtendis.

Voorbeeld: In een applicatie voor het verwerken van bestellingen kunnen documenten zoals facturen of mailings van een klant worden opgezocht die in Xtendis zijn opgeslagen.

Zo'n integratie werkt door een URL toe te voegen in de vorm van een knop of link waarop gebruikers kunnen klikken om toegang te krijgen tot één of meerdere documenten of dossiers in Xtendis. Dit maakt het werken met de dagelijkse applicatie in combinatie met Xtendis veel efficiënter omdat gebruikers Xtendis niet handmatig hoeven te openen en zelf naar de documenten of dossiers hoeven te zoeken.

Hoe het werkt

De URL is een zoekopdracht die wordt gegenereerd met behulp van de Lookup testerpagina in de sectie Functioneel beheer van Xtendis.

Voorbeeld: https://mijn-xtendis.nl/web/weblauncher.aspx?archiefnaam=Central&doc_Document%20date=13-03-2023

Het resultaat kan een enkel document of dossier zijn, of meerdere documenten of dossiers.

Omdat gebruikers toegang krijgt tot Xtendis, moeten zij in Xtendis als gebruiker bestaan en voldoende toegangsrechten hebben om de documenten of dossiers te bekijken.

Gebruikers kunnen de volgende soorten toegang krijgen:

• Volledige toegang, vergelijkbaar met het openen van Xtendis en het handmatig zoeken naar de documenten of dossiers. Dit gebeurt via de zogenaamde 'Web launcher'.
• Beperkte toegang, waarbij alleen basisfuncties zoals het afdrukken en downloaden van de documenten beschikbaar zijn. Dit gebeurt via de zogenaamde 'Web lookup'.

Authenticatie van de gebruiker verloopt op dezelfde manier als bij de reguliere webapplicatie.

Voorbeeld: Windows-verificatie voor de webtoepassing betekent ook Windows-verificatie voor de webzoekopdracht; ADFS-koppeling voor de webinterface betekent ook ADFS voor de Web lookup.

Het gebruik van de Web launcher vereist het toegangsrecht om het Web te gebruiken (het recht om de standaard webapplicatie te gebruiken).

Het gebruik van de Web lookup vereist het toegangsrecht 'lookup use'.

Opmerking: Als u een workflow voor documenten gebruikt (met behulp van flow-knoppen) in combinatie met de Web lookup, moet de Web launcher worden gebruikt. Dit komt omdat de flow-knoppen geen deel uitmaken van de basisfuncties die beschikbaar zijn met de Web lookup.

Basisconfiguratie

Het zogenaamde 'endpoint' van de URL bepaalt de zoekmethode en is daarmee een belangrijk onderdeel van de inrichting.

De volgende endpoints zijn beschikbaar:

• Voor de Web launcher: weblauncher.aspx?
• Voor de Web lookup: weblookup.aspx?

De logica van een zoekopdracht string is hetzelfde in zowel de Web lookup als de Web launcher. Het volgende is belangrijk:

• Het archief waarin de zoekopdracht moet worden uitgevoerd.

Voorbeeld: archivename=General Archive

• Er moet minimaal één zoekcriterium worden opgenomen.

Voorbeeld: &invoicenumber=2018004

Deze zoekcriteria kunnen kenmerken zijn van het document en/of het dossier. Daarnaast kan er gezocht worden op tal van technische kenmerken.

Om te helpen met het opbouwen van de zoekopdracht kan de Lookup tester in de sectie Functioneel beheer van Xtendis worden gebruikt. Zie De zoekopdracht samenstellen hieronder.

Opmerking: Een kenmerk kan maar één keer worden vermeld in de zoekopdracht.

De pagina openen

Open de pagina door naar het Functioneel beheer van Xtendis te gaan en in het menu aan de linkerkant op Lookup tester te klikken.

De zoekopdracht samenstellen

De Lookup testerpagina maakt het eenvoudig om de zoekopdracht samen te stellen. Het bevat verschillende componenten die van boven naar beneden worden gebruikt.

Stap 1. Kies uit de archieflijst het archief waarin gezocht moet worden.

Stap 2. Kies in de lijst met toegangstypen de Web launcher of de Web lookup.

Stap 4. (Optioneel) Schakel de optie Toon aantal gevonden documenten in om het aantal documenten te zien dat de zoekopdracht vindt.

Stap 4. Klik in de lijst met kenmerken op het plusteken voor het kenmerk dat u wilt opnemen. Klik er nogmaals op om het te verwijderen.

Tip: Gebruik het filter om het aantal kenmerken dat wordt weergegeven te verminderen door ofwel een categorie uit de lijst te kiezen en/of door (een deel van) de naam te typen.

Opmerking: Zie de sectie Geavanceerde instellingen hieronder voor krachtigere instellingen, zoals het gebruik van datumreeksen, meerdere waarden en meer.

Stap 5. (Optioneel) Selecteer het tabblad Samenvatting om een samenvatting van de zoekopdracht weer te geven als tekst of als visuele weergave.

Stap 6. (Optioneel) Als er een speciaal teken moet worden opgenomen, zoals een %-teken of een teken met accent, gaat u naar het tabblad Speciale tekens en voert u het teken in een van de velden in. De codering wordt weergegeven naast het veld.

Stap 7. Klik op de knop Link kopiëren om de URL naar het klembord te kopiëren.

Stap 8. Test de link door deze in een webbrowser te plakken om te zien of deze de gewenste resultaten geeft.

Geavanceerde configuratie

Afgezien van het gebruik van de hulpmiddelen op de pagina, kan de zoekopdracht worden verbeterd door geavanceerde opties te gebruiken, zoals datumreeksen, meerdere waarden en meer. Deze worden hieronder uitgelegd.

Archief definitie

Voor de archiefdefinitie kunt u verwijzen naar de archiefnaam of als alternatief het archiefid.

OF constructies

Een OF-constructie kan worden samengesteld door te verwijzen naar meerdere waarden, gescheiden door een puntkomma.

Datumnotatie

Datumvelden zijn altijd opgebouwd in het volgende formaat: dd-mm-jjjj.

Datumreeks

Datumreeksen kunnen worden geconstrueerd door de letter t op te nemen.

Decimaal formaat

Decimalen in numerieke waarden worden weergegeven door een decimaalteken.

Voorbeeld: 506.60.

Numerieke reeksen

Numerieke reeksen kunnen worden geconstrueerd door de letter t op te nemen.

Velden met meerdere waarden

Er kan naar meerdere waarden binnen hetzelfde veld worden verwezen door ze te scheiden met een puntkomma.

Voorbeeld: &tags=ProcessorOvereenkomst;Planning

Opmerking: Dit is alleen van toepassing op velden die in de archiefdefinitie als meervoudig zijn aangemerkt.

Zoekvelden tonen wanneer er maar één resultaat is gevonden

Info: Dit is alleen van toepassing op het gebruik van de Web launcher.

Als er slechts één resultaat wordt gevonden, is het standaardgedrag dat alleen het item wordt weergegeven zonder opties om verder te zoeken.

Indien nodig kunnen de zoekopties in dit scenario worden opgenomen door &showAll=1 aan de query toe te voegen.

Example: 
https://mijn.xtendis.nl/web/weblauncher.aspx?archiefnaam=Central&t_INDEXEERDATUM=21-02-2023&showAll=1.

Alleen het meest recente actieve document weergeven

Info: Deze functie vereist Xtendis 7.3.12 of hoger (zie hoe u kunt controleren welke versie van Xtendis u gebruikt).

Om de gebruiker naar het laatst actieve document te verwijzen, gebruikt u &showall=false.

Dit toont een weergave met alleen het actieve document, in plaats van een complexe gebruikersinterface met alle documenten.

Bijzondere tekens

Documentkenmerken en -waarden moeten URL-veilig zijn, wat betekent dat ze geen tekens mogen bevatten die iets anders in een URL zouden kunnen betekenen.

Voorbeelden zijn de ampersand, de hekje, en de punt (&, #, en .).

Om deze in de URL te kunnen gebruiken, moeten ze 'URL-encoded' zijn.

De juiste manier van coderen is te vinden op internet. Enkele bronnen om te gebruiken zijn:

• Percent-encoding op mozilla.org
• The HTML URL Encoding Reference op w3schools.com
• URL Encoding op blooberry.com

De eerder genoemde Lookup tester kan ook helpen bij het vinden van de juiste codering.

Documentkenmerken versus dossierkenmerken

Wanneer dezelfde kenmerken voorkomen in de referenties van zowel het document als het dossier, dan is het verstandig om de kenmerken een voorvoegsel te geven.

Gebruik doc_ voor documentkenmerken en dsr_ voor dossierkenmerken.

Dossiers zoeken

Bij het zoeken naar dossiers mag de zoekreeks alleen worden uitgebreid met 'launch=dsr' .

Dit geeft de gebruiker een lijst met dossiers van waaruit deze geopend kunnen worden.

Documentkenmerken kunnen niet worden gebruikt voor het zoeken naar dossiers.

Functies die beschikbaar zijn in de Web lookup

De beschikbare functies in de Web lookup zijn beperkt. Ze kunnen indien nodig worden aangevuld door in de Xtendis Cockpit onder Algemene instellingen de optie WeblookupEditionType te wijzigen tussen Eenvoudig en Volledig.

Opmerking: Als de volledige optie nodig is, is het beter om over te schakelen van de Web lookup naar de Web launcher.

Geen resultaten

Wanneer de zoekopdracht wordt uitgevoerd, kan het voorkomen dat er geen resultaten worden weergegeven en dat er een melding verschijnt dat de zoekopdracht niet correct was.

Dergelijke gevallen worden gerapporteerd in de logbestanden van waaruit kan worden geanalyseerd of er iets mis is gegaan met de vertaling van de URL naar een zoekopdracht.

Enkele veelvoorkomende problemen zijn de volgende:

• Het archiveId of de archiefnaam is niet correct (de archief-ID's kunnen verschillen tussen test en productie).
• Er staat een spatie voor of achter de archiefnaam.
• Het document- of dossierkenmerk is verkeerd gespeld.
• Zoekopdrachten moeten ten minste één kenmerk bevatten.
• De URL bevat een speciaal teken.

Wildcards

Het percentageteken kan worden gebruikt als wildcard voor constructies zoals 'begint met', 'bevat' of 'eindigt met'.

Omdat het een speciaal teken is, moet het worden gecodeerd als %25.

De volgende tabel bevat enkele voorbeelden: