Verwerken DSO-bijlagen [Documentatie]

Deze pagina is alleen-lezen. Je kan de broncode bekijken maar niet veranderen. Neem contact op met de beheerder als je denkt dat dit niet klopt.
====== Verwerken DSO-bijlagen  ======

Er zijn twee manieren waarop OpenWave de daadwerkelijke bijlagen uit het DSO binnenhaalt en verwerkt.
  * OpenWave haalt zelf de bijlagen en verzoek.pdf op met de DSO-AfhandelenVerzoek-API. Dit gebeurt na het verwerken van een binnengekomen DSO-verzoekbericht. Zie hiervoor het kopje //Ophalen en registreren van bijlages en verzoek.pdf// van [[openwave:1.33:applicatiebeheer:probleemoplossing:programmablokken:verwerking_dso_stam_berichten]]\\ Deze weg is te prevaleren omdat alleen de nodige documenten worden opgehaald op grond van gevraagde registratienummers.
  * OF de digi-koppelaar zend de bijlages naar een endpoint van OpenWave. Deze methode heeft het nadeel dat alle documenten, ook reeds bestaande en geregistreerde, en ook documenten bij genegeerde kopieberichten, worden verzonden. De controle of een document reeds bestaat kan alleen op bestandnaam. \\ Dit hoofdstuk gaat verder over deze situatie.  

Indien ingesteld is dat OpenWave zelf de bijlagen ophaalt met de instelling //Sectie: OWB en Item: OphalenDSODocsViaApi// aangevinkt EN de instelling //Sectie: DocumentRegistreren en Item: AlleOLODSOUploads// ook aangevinkt (of de kolom tbcompartiment.dldocregalleolodsouploads indien het gaat om een compartiment) dan worden de bijlagen die de digi-koppelaar naar het daartoe bestemde endpoint van OpenWave stuurt genegeerd.

===== Verwerken DSO-bijlagen vanuit digi-koppelaar  =====

Dit is het geval indien  de instelling //Sectie: OWB// en //Item: OphalenDSODocsViaApi// **NIET** aangevinkt is OF indien de instelling //Sectie: DocumentRegistreren// en //Item: AlleOLODSOUploads// **NIET** aangevinkt is ( of - als het verzoekbericht gaat over een compartiment - indien tbcompartiment.dldocregalleolodsouploads niet is aangevinkt).

Voor het uploaden vanuit de digi-koppelaar van DSO-bijlagen naar OpenWave is een endpoint aanwezig.\\ 
Authenticatie op het endpoint vindt plaats met een username en password, met HTTP AUTH Basic. De bestanduploads hebben per upload twee parameters nodig: de filename en het DSO-nummer waar het bestand bij hoort.
De bestand-upload is een POST request (enctype="multipart/form-data). De twee parameters kunnen in de POST payload of als GET parameter worden meegestuurd. 

<adm example>
Een voorbeeld:
  * a) filename='test.docx'
  * b) DSO-nummer='0123456789'
Een voorbeeldaanroep in het geval van een request met twee GET parameters: ''<nowiki>https://[serveradres]/dso/bestanden/index.php?dsonummer=0123456789&filename=test.docx</nowiki>''
</adm>

<adm warning>
Het kan zijn dat de digi-koppelaar het OIN-nummer van het bevoegd gezag of behandeldienst toevoegt als prefix aan de documentnaam gevolgd door een hyphen ('-') gevolgd door het DSO-verzoeknummer en een hypen, gevolgd door DSO-volgnummer en een hyphen. Is dat het geval dan ziet de aanroep van bovenstaand voorbeeld er bijvoorbeeld zo uit: ''<nowiki>https://[serveradres]/dso/bestanden/index.php?dsonummer=0123456789&filename=00000003332595610000-0123456789-000-test.docx</nowiki>'' 
 
In het geval van complexe verzoeken in samenwerkingsverband, kan het zijn dat eenzelfde document twee keer (tegelijkertijd) naar het OpenWave endpoint wordt verzonden: één keer met het OIN van het bevoegd gezag in de prefix en één keer net het OIN-nummer van de behandeldienst in de prefix. In dat geval zal OpenWave dubbele documenten negeren, maar is niet goed af te vangen onder welk OIN-nummer (zie hieronder bij dubbele documenten).
</adm>

OpenWave plaatst het document eerst op de DSO-tempmap (kolom //Tekst// van de instelling://Sectie: OWB// en //Item: TussenMapDSOUploadfiles//) onder de naam verzoeknummer + underscore + de aangeleverde naam van de digi-koppelaar.\\
Vanuit deze tempmap wordt het document vervolgens verwerkt bij de juiste zaak en opgeslagen onder de naam die door de digi-koppelaar is aangeleverd.\\
Dat wil zeggen óf - via stuf zaak/dms - in het DMS óf op de fileserver op de map gedefinieerd door de kolom //Tekst// van instelling //Sectie: Aanmaakmappen// en waarbij item begint met //Omgeving_// en waarbij //Getal2 = 1//.\\
Indien ingesteld dat het document geregistreerd moet worden in tbcorrespondentie dan gebeurt dat in de kolom dvdocfilenaam met - in geval van opslag in DMS - alleen met de bestandnaam en - in geval van opslag op fileserver - met het volledige pad + bestandsnaam.


==== Werkwijze DSO-bijlagen via digi-koppelaar ====

De DSO/PHP-luisterservice plaatst de binnengekomen file op een map op de webserver.\\
Deze map is gedefinieerd in kolom //Tekst// van de instelling: //Sectie: OWB// en //Item: TussenMapDSOUploadfiles//.\\
In de kolom //Tekst// staat de mapnaam op de webserver: deze mapnaam MOET eindigen op de karakterreeks: '/openwave/uploaddso/' en beginnen met een '/'.
De luisterservice roept hiertoe de API getAuthorisation aan en daarna met de verkregen sessie-sleutel de API geefInstellingen (om de DSOUploadmap op te halen) en tenslotte de API Uploadfile.

Adres en poort waar deze OpenWave API's staan te luisteren staan in de map config in de file openwave.ini op dezelfde machine als de luisterservice. Dit is een systeembeheerinstelling. 

De user/pass waarmee getAuthorisation aangeroepen wordt (dezelfde als afgesproken met de leverancier van het document) moet wel opgenomen zijn in de medewerkerstabel waarbij:
  * de user toegang moet hebben tot de browserversie 
  * EN //passworddatum verloopt nooit// aangevinkt is 
  * EN de kolom //2-factor authentication opheffen// aangevinkt is
  * EN de user lid is van een rechtengroep die minimaal bij de omgevingszaken het recht //Creëren en uploaden documenten// aangevinkt heeft staan
  * EN de user lid is van een rechtengroep die minimaal op één van de modules (bouw/sloop, horeca, handhavingen, APV/overig/ milieu/gebruik/ info, omgeving of inrichtingen) kijkrechten heeft.
Alle overige rechten kunnen dus uitgevinkt staan voor deze medewerker.

De luisterservice roept nu per document de API uploadfile aan.
De API uploadfile moet - naast de parameter paramidentifier met daarin de filenaam - voorzien worden van de parameter paramauto die aangeeft welk automatisch proces een document probeert op te slaan. Het luisterproces geeft de waarde 'DSO' door en als paramidentifier de documentnaam opgebouwd volgens het masker dsonr_filenaam.
Dus bijvoorbeeld 123456789_Plaatje.jpg of 0123456789_00000003332595610000-0123456789-000-test.docx.

Zo gauw de API uploadfile de focus heeft worden alle files die op de //TussenMapDSOUploadfiles// staan en die een filedatum/timestamp hebben ouder dan het aantal uren hetgeen is ingesteld in //Getal1// van de instelling van //Sectie: OWB// en //Item: MaxUurUpload//, verwijderd.

==== Bepaling zaak in OpenWave ====

Het DSO-nummer wordt gebruikt om de omgevingszaak te traceren (tbomgvergunning.dvlvoaanvraagnr) en daarbij eventueel het nodige externe zaak/DMS nummer op te halen (dvintzaakcode). Aangezien deze laatste ook door automatische processen worden aangemaakt kan er een vertraging wenselijk zijn: als het programma het DSO-nummer niet kan vinden of aan het DSO-nummer is nog geen externe zaakidentificatie gekoppeld dan kan in een loop nog een aantal maal een poging worden gedaan.

Deze loop is qua aantal en wachtduur instelbaar met de instelling //Sectie: KoppelingDOCNAARDMS// en //Item: WachtOpExtAantalSeconden//. In //Getal1// staat het aantal seconden dat gewacht wordt (default 2, maar aanbevolen: 180) alvorens opnieuw te zoeken en in //Getal2// staat het aantal maal dat dat herhaald mag worden (default 5, maar aanbevolen: 3).

==== Controle dubbele documenten ====

Indien OpenWave de zaak heeft gevonden kan het zijn dat een extra controle wenselijk is of het document al bestaat bij de gevonden zaak. Dat gebeurt indien bijlages ook worden geregistreerd in tbcorrespondentie (indien dus //Sectie: DocumentRegistreren// en //Item: AlleOLODSOUploads// is aangevinkt) EN de instelling //Sectie: Koppeling OLO en Item: CheckOpDubbeleDocumentnaam// is aangevinkt. Dan checkt OpenWave of de documentnaam reeds voorkomt in de geregistreerde documenten bij de gevonden zaak (kolom dvdocfilenaam). Zo ja, dan wordt het document niet geplaatst en wel een kaart gemaakt in tabel mislukte DSO-bijlages.  

{{openwave:applicatiebeheer:probleemoplossing:programmablokken:dsodubbelecheckopingeschotendocumenten.png?900|dsodubbelecheckopingeschotendocumenten}}

**ad 1. De bijlages worden door de digi-koppelaar geplaatst op het daartoe bestemde endpoint**\\
De bijlagenaam is dus de documentnaam zoals door Jnet of door EnableU is doorgeschoten.\\
Indien vanuit Jnet ingeschoten dan bestaat de bijlagenaam uit het OIN-nummer (20 posities) gevolgd door hyphen gevolgd door DSO-verzoeknummer (13 posities) gevolgd door hyphen gevolgd door het versienummer (bestaande uit drie posities) en dan een hyphen en dan de pure documentnaam).  
Indien door EnableU dan is de bijlagenaam gelijk aan de pure documentnaam.
<adm example>
Bij Jnet zien de bijlagenamen bij het oorspronkelijke STAM-bericht er als volgt uit: 
    00099999999999999999-0123456789123-000-kameel.docx
    00099999999999999999-0123456789123-000-schaap.docx
Bij Jnet zien de bijlagenamen bij een aanvullingsbericht er als volgt uit: 
    00099999999999999999-0123456789123-001-kameel.docx
    00099999999999999999-0123456789123-001-schaap.docx
Bij EnableU zijn de bijlagenamen in beide gevallen:
    kameel.docx
    schaap.docx
</adm>
Aan de bijlagenamen is niet af te leiden of het document daadwerkelijk is gewijzigd ten opzichte van het origineel of niet.

**ad 2. Bestaat de bijlage wel fysiek op de tempmap?**\\
De tempmap is in dit geval de tussenmap op de server gedefinieerd door de kolom //Tekst// van instelling //Sectie: OWB// en //Item: TussenMapDsoUploadfiles//.\\
De filenaam die daar is opgeslagen is de bijlagenaam (zie ad1) voorafgegaan door het DSO-verzoeknummer en een hypen.

**ad 3. is de bijlagenaam een Jnet of een EnableU naam?**\\
OpenWave kijkt hiertoe naar //Getal 1// van de instelling //Sectie: Koppeling OLO// en //Item: CheckOpDubbeleDocumentnaam//. Indien 1 dan wordt er vanuit gegaan dat de bijlagenaam een EnableU-naam is. Indien ongelijk aan 1 dan dus een Jnet-naam.

**ad 4. Bestaat de bijlagenaam reeds in tbcorrespondentie.dvdocfilenaam?**\\
In geval van Jnet-naam wordt de bijlagenaam gezocht zonder OIN-nummer. Dus stel de bijlagenaam is //00099999999999999999-0123456789123-000-kameel.docx//, dan wordt hier gekeken of de string //0123456789123-000-kameel.docx// voorkomt in de documentnamen van tbcorrespondentie bij de omgevingzaak die hoort bij het verzoeknummer.\\
Er wordt gezocht binnen de kolom dvdocfilenaam van tbcorrespondentie: het laatste gedeelte van de dvdocfilenaam moet gelijk zijn aan de bijlagenaam.

**ad 5. Bestaat de pure bijlagenaam en dsovolgnr in tbomgoloberichten?**\\
Het DSO-volgnummer is bij Jnet bepaald door het betreffende gedeelte uit de bijlagenaam en bij EnableU door de kolom ***dsovolgnr** van de betreffende omgevingzaak.\\
OpenWave kijkt alleen indien het DSO-volgnummer ongelijk aan //000// is of er een kaart bestaat in tbomgoloberichten bij de betreffende omgevingzaak met als dvlvobestandnaam de pure bijlagenaam EN waarbij dvdsovolgnr gelijk is aan DSO-volgnummer EN waarbij dddsovervallen leeg is. Die pure bijlagenaam is bij EnableU gelijk aan de bijlagenaam. Bij Jnet is de pure bijlagenaam de bijlagenaam zonder OIN-nummer en zonder verzoeknummer en zonder volgnummer. \\
Deze stap geldt niet voor de verzoek.pdf want dit is geen bijlage in tbomgoloberichten (en zit dus ook niet in het STAM-bericht). 

**ad 6. Bepaal versienummer bij Jnet berichten**\\
Alleen bij Jnet-berichten zit het versienummer (DSO-volgnummer) in de bijlagenaam. Zie bij ad 1. Indien de bijlagenaam toch niet volgens het stramien OIN-verzoeknr-versienr-documentnaam is opgebouwd dan wordt '000'als versienummer genomen.

**ad 7. Haal OIN-nummer uit de bijlagenaam**\\
Alleen bij Jnet-berichten zit het OIN-nummer in de bijlagenaam. Zie bij ad 1. Indien de bijlagenaam toch niet volgens het stramien OIN-verzoeknr-versienr-documentnaam is opgebouwd dan wordt deze stap overgeslagen.
In het geval dat documenten worden verzonden naar OpenWave die horen bij een zogenaamd DSO kopiebericht, dan bevat de documentnaam het OIN-nummer van het bevoegd gezag. Hetzelfde document kan echter al aanwezig zijn in OpenWave onder het OIN-nummer van de behandeldienst. De controle vindt daarom plaats op een substring van de documentnaam (zonder het OIN-gedeelte) mits //Getal1// van de instelling //Sectie: Koppeling OLO// en //Item: CheckOpDubbeleDocumentnaam// ongelijk aan waarde 1 is (dus indien het gaat om Jnet). 

Dit kopiebericht is bijvoorbeeld het geval als een gemeente geen eigen opvang heeft van DSO-berichten en hiervoor de Omgevingsdienst gebruikt. De omgevingsdienst verwerkt het STAM-bericht voor het bevoegd gezag (de gemeente). Er gaat echter altijd een kopie vanuit het DSO naar het bevoegd gezag: in dit geval is dat wederom dezelfde OpenWave installatie. OpenWave voorkomt altijd dat een dubbele zaak (dus met hetzelfde DSO verzoeknummer) wordt aangemaakt binnen één OpenWave installatie. De namen van de nagestuurde documenten bij de kopiezaak zijn echter niet gelijk aan de originelen die de omgevingsdienst als behandeldienst al heeft ontvangen. Hetzelfde document begint in de originele zaak met het OIN-nummer van de omgevingsdienst en bij de kopiezaak is dat het OIN-nummer van het bevoegd gezag.

**ad 8. Document wordt opgeslagen en registratie wordt aangemaakt**\\
Bij Jnet-documenten wordt de volledige bijlagenaam (dus incl. OIN-nummer, verzoeknummer en versienummer) gebruikt bij de registratie in tbcorrespondentie.

**ad 9. Stop, Bijlage wordt genegeerd**\\
De bijlage wordt niet verwerkt in OpenWave. Wel wordt een kaartje aangemaakt in tbadexternupload. Zie tegel //Mislukte DSO bijlages// in het servicecentrum-portaal

===== Opslaan van document in fileshare of in DMS =====

Het daadwerkelijk plaatsen van de file (op fileshare of Stuf zaak/DMS) gaat gelijk aan het beschrevene in het lemma [[openwave:1.33:applicatiebeheer:probleemoplossing:programmablokken:upload_document|Upload document(en)]], waarbij het volgende extra geldt:
  * bij plaatsing via fileshare kijkt het programma naar de unieke map gedefinieerd door //Sectie: AanmaakMappen// en //Item begint met 'Omgeving_'// EN //Getal2// = 1
  * bij plaatsing via STUF Zaken kijkt het programma wat betreft het documenttype indien GEEN compartiment naar kolom //Tekst// van instelling //Sectie: KoppelingDOCNAARDMS// en //Item: OloDocType// (defaultwaarde 'OLO'), indien WEL compartiment naar de tekst in het veld //DSO documenttype// in het detailscherm van de compartimentsrechten in het beheerportaal-Nieuw
  * bij plaatsing via STUF Zaken kijkt het programma ook wat betreft metadata vertrouwelijkheid indien GEEN compartiment naar kolom //Tekst// van instelling //Sectie: KoppelingDOCNAARDMS// en //Item: OloVertrouwelijkheid// (defaultwaarde 'OPENBAAR'), indien WEL compartiment naar de tekst in het veld //DSO vertrouwelijkheid// in het detailscherm van de compartimentsrechten in het beheerportaal-Nieuw
  * wat betreft Auteur bij StUF zaken: deze krijgt de waarde //onbekend//
  * indien zowel is ingesteld dat documenten op de fileserver geplaatst kunnen worden als in een DMS, dan zullen de DSO-bijlages in het DMS worden geplaatst, tenzij de instelling //Sectie: Koppeling OLO// en //Item: BestandenNaarFileserver// aangevinkt is: dan krijgt de fileserver-variant de voorkeur.

===== Automatische registratie van document =====

Indien de zaak speelt in een compartiment dan kijkt OpenWave of de kolom //DSO uploads registreren// (tbcompartiment.dldocregalleolodsouploads) aangevinkt is bij het betreffende compartiment onder de tegel //Compartimentsrechten// in beheerportaal-Nieuw, kolom Gebruikers. Indien de zaak NIET speelt in een compartiment dan kijkt OpenWave naar de instelling //Sectie: DocumentRegistreren// en //Item: AlleOLODSOUploads//. Aangevinkt dan wordt van de bijlage automatisch een registratie gemaakt in tbcorrespondentie met:
  * **Documenttype** (dvdoctype_oms) indien GEEN compartiment met kolom //Tekst// van Instelling //Sectie: KoppelingDOCNAARDMS// en //Item: OloDocType// (defaultwaarde 'OLO'), indien WEL compartiment naar de tekst in het veld //DSO documenttype// in het detailscherm van de compartimentsrechten in het beheerportaal-Nieuw
  * **Definitief** met indien //Getal1// van de instelling //Sectie: DocumentRegistreren// en //Item: AlleOLODSOUploads// aangevinkt is, met (N)ee, anders met (J)a
  * **Richting** met (B)innenkomend 
  * **dldsovertrouwelijkheid** met de waarde (T of F) van de bijbehorende bijlageverwijzing in tbomgoloberichten
  * **Vertrouwelijkheid** (dnkeyvertrouwelijkheid) 
    * indien DSO vertrouwelijkheid (dldsovertrouwelijkheid) ='T' dan  wordt de  kolom //Tekst// van Instelling //Sectie: DSO// en //Item: VertalingVertrouwelijkheid// opgezocht in de tabel tbvertrouwelijkheid 
      * indien gevonden dan wordt de tbvertrouwelijkheid.dnkey in deze kolom dnkeyvertrouwelijkheid geplaatst 
      * anders (wel T maar instelling niet gevonden) dan wordt de  kolom //Tekst// van Instelling //Sectie: DSO// en //Item: VertalingVertrouwelijkheid// opgezocht in de tabel tbvertrouwelijkheid met als defaultwaarde //'openbaar//':
        * indien gevonden dan wordt de tbvertrouwelijkheid.dnkey in deze kolom dnkeyvertrouwelijkheid geplaatst
        * nog niet gevonden dan blijft de dnkeyvertrouwelijkheid leeg.
    * Indien dldsovertrouwelijkheid) ='F 'dan 
      * indien GEEN compartiment wordt met kolom //Tekst// van Instelling //Sectie: KoppelingDOCNAARDMS// en //Item: OloVertrouwelijkheid// (defaultwaarde 'openbaar') gezocht in tbvertrouwelijkheid:
        * indien gevonden dan wordt de tbvertrouwelijkheid.dnkey in deze kolom dnkeyvertrouwelijkheid geplaatst
        * indien niet gevonden dan blijft de dnkeyvertrouwelijkheid leeg.
      * indien WEL compartiment dan wordt de tekst in het veld //DSO vertrouwelijkheid// op het detailscherm van de compartimentsrechten in het beheerportaal gezocht in tbvertrouwelijkheid (default //'openbaar'//):
        * indien gevonden dan wordt de tbvertrouwelijkheid.dnkey in deze kolom dnkeyvertrouwelijkheid geplaatst
        * indien niet gevonden dan blijft de dnkeyvertrouwelijkheid leeg.
  * **Omschrijving** met de waarde van kolom dvomschrijving van de corresponderende kaart uit de tabel tbomgoloberichten (de tabel met opgesomde documenten uit het DSO-verzoekbericht).


===== Technische instelling =====

WSAS moet benaderd worden op poort 9763(HTTP), dit is een onopgeloste bug. Op poort 9443(HTTPS) werkt het upload.php script niet.
Voer de instellingen in de PHPcake configuratie "openwave.ini" in als volgt:
  * port = 9763
  * use_protocol = http
  * use_protocol_endpoint = Http

===== Loggen =====

In plaats van dat de tabel tbUpload gevuld wordt met een log (zowel gelukt als niet gelukt) wordt nu de beheertabel tbBadExternUpload gevuld met **alleen de mislukte plaatsingen**. In alle gevallen (gelukt of niet gelukt) wordt de oorspronkelijke file op de TussenMapDSOUploadfiles vernietigd.

{{tag>openwave:1.33:applicatiebeheer:functionaliteiten:dso}}