Functionele beschrijving view functie
Inhoud
LET OP ook deze functie moet een modelid hebben. Omdat de toekomstige view-ids niet uniek zijn over de modellen heen.
- /gemma/gemma_2/view/id-129083291890821
- /gemma/gemma_softwarecatalogus/view/id-129083291890821
Omschrijving[bewerken]
De softwarecatalogus kan met deze functie een GEMMA architectuurplaat laten renderen met daarop ingevuld de pakketten die een gemeente, samenwerking of leverancier heeft geregistreerd.. Softwarecatalogus vraagt aan GEMMA Online om een plot van een GEMMA view. De API heeft de volgende mogelijkheden:
- Servicecall voor het genereren van specifieke view met daarop geplot de meegestuurde referentiecomponenten en de ervoor gebruikte pakketten
- Servicecall retourneert een URL naar gegeneerde plaat
- Kan SVG of PNG, via het Rendering attribuut.
- Servicecall retourneert een imagemap resultaat aan
Beveiliging[bewerken]
Alle gegenereerde platen worden opgeslagen op onze applicatieserver. Omdat de views gevoelige informatie kunnen bevatten worden de URLS die gegenereerd gehashed. Deze hash bestaat uit een base64 encoded string die vervolgens met een IV wordt geserialiseerd. Wij (ArchiXL) leveren een token bestand aan waarmee je de base6e-encoded string mee kan deserializeren. Let op: de beveiliging staat momenteel uit.
Eisen[bewerken]
| Veld | Inhoud | Voorbeeld |
|---|---|---|
| $key | Encryptie: sha256 encoded hash van het tokenbestand. | hash( 'sha256', $token ); |
| $iv | Eerste 16 karakters van de $key | substr( hash( 'sha256', $token), 0, 16 ); |
| $resultaat | De decryptie met AES-256-CBC van de base64-encoded string met de $key en $iv string | openssl_decrypt( base64_decode( $string ), 'AES-256-CBC', $key, 0, $iv ); |
Voorbeeldcode deserialisatie[bewerken]
$string = "TkVnYzFqMm5lNlRQcEcxWlpZVHJFSjZNUGVma2lweDQzTEt2cm5hc3poKzZpNmFFcEJXdmZ1QUpteTlwNWJBMEYrazB0VVNPK0FnVXdnZ2x0ZHdHOHBkUnRYWmcyUWxobDMxa3ZPeVFyYmp6ZVUrM0pUdlpWU0hzdjlFTlIzRjA=";
$token = file_get_contents('archixl.token');
$key = hash('sha256', $token);
$iv = substr( hash( 'sha256', $token ), 0, 16 );
$result = openssl_decrypt( base64_decode( $string ), 'AES-256-CBC', $key, 0, $iv );
Input/output[bewerken]
API aanroep met versieaanduiding: api.php?action=gemma&view=<GUID van de gevraagde VIEW>&format=<format>. De te mappen gegevens worden als een POST actie in JSON formaat geleverd aan deze URL, kijk naar voorbeeld op het formulier
- alle opmaak die nodig is om een plaat te tonen wordt in de json file meegegeven, in plaats van de situatie dat de API deze intelligentie moet gaan berekenen, daarmee houd je de opmaak ook flexibeler. GEMMA Online kent alles van het GEMMA Model. De SWC bevat alle kennis van Softwarepakketten, en blijft flexibel in de gewenste weergave, zonder aanpassingen in de GEMMA API.
Invoer[bewerken]
Verplichte attributen om mee te geven via GET[bewerken]
| Veld | Verplicht | Toelichting |
|---|---|---|
| viewid | Ja | De ID van de te renderen architectuurplaat |
| imageformat | Ja | Welk formaat moet worden gebruikt. Standaard worden SVG gebruikt. Mogelijke opties: SVG, PNG. |
| size | Nee | Als PNG gekozen wordt, is het mogelijk om zelf een breedte in pixels aan te geven. Maximaal 10.000 pixels |
Verplichte attributen om mee te geven via POST[bewerken]
| Veld | Verplicht | Toelichting |
|---|---|---|
| json | Ja | JSON geserializeerde string. |
Verplichte inhoud JSON velden[bewerken]
Het JSON veld moet de volgende eigenschappen bevatten:
| Eigenschap | Verplicht | Toelichting |
|---|---|---|
| Title | Ja | De regel de titel van het model. Geplaatst boven in de view, gecentreerd |
| Infoboxes | Ja | Lijst met 1 of meer infoboxes |
| Pakketten | Ja | Lijst met 1 of meer pakketten |
Eigenschappen Infoboxes[bewerken]
De waarde infoboxes moet een waarde hebben van de volgende attributen:
| Eigenschap | Verplicht | Toelichting |
|---|---|---|
| Infoboxtitle | Ja | De regel de titel van het model. Geplaatst boven in de view. |
| Infoboxposition | Ja | Positie van de infobox, kan left op right zijn. |
| Infoboxlines | Ja | Lijst met regels, kan 1 of meerdere regels bevatten. |
Infoboxlines omschrijving[bewerken]
Let op: er kunnen meerdere definities van de infoboxlines zijn. Als dit het geval is, verwachten wij een array!
| Eigenschap | Verplicht | Toelichting |
|---|---|---|
| Style | Ja | CSS style van de tekstregel |
| Value | Ja | Tekstregel inhoud |
Eigenschappen Pakketten[bewerken]
De waarde Pakketten moet een waarde hebben van de volgende attributen:
Uitvoer[bewerken]
De uitvoer is in een door uw gespecifieerd formaat beschikbaar. Uitvoer velden:
| Eigenschap | Toelichting |
|---|---|
| warnings | Placeholder voor waarschuwingen. Let op; om de waarde uit te lezen moet je subset 'result' bekijken. |
| warnings.result | String met alle foutmeldingen. Explode \n om nieuwe regels uit te lezen. |
| viewdiagrams | Lijst met items. Zie item definitie hieropnder. |
| viewdiagrams.item.id | ID van de gegenereerde plaat |
| viewdiagrams.item.urlenc | Gehashde string van de plaaturl |
| viewdiagrams.item.imagemap | Collectie van (html) area-tag attributen. Zie w3schools.map voor meer informatie. Uitvoer attributen: coords, href, alt. |
Foutmeldingen[bewerken]
De API kan verschillende foutmeldingen terug geven. Let op; bij foutmeldingen wordt de API call direct geannuleerd. Er zit een onderscheid tussen warnings en foutmeldingen. De volgende foutmeldingen zijn mogelijk:
| Melding | Omschrijving |
|---|---|
| Geen POST ontvangen | Het is niet mogelijk om een view te genereren zonder POST actie. |
| Ongeldige json | De aangeleverde JSON in de POST bevat geen juiste waarde. |
| Geen JSON data ontvangen | Er is geen JSON aangeleverd in de POST actie. Let op: het naam van het veld dat we moeten ontvangen is 'json'. |
| Er is geen valide pakket informatie ontvangen | Er is geen juiste informatie ontvangen voor het veld 'Pakketten'. Zie link voor de opmaak. |
| Er zijn geen pakketten ontvangen | Er zijn geen pakketgegevens ontvangen. Zie link voor de opmaak. |
| Er is geen valide infobox informatie ontvangen | Er is geen juiste informatie ontvangen voor het veld 'Infoboxes'. Zie link voor de opmaak. |
| Er zijn geen infoboxes ontvangen | Er zijn geen infoboxes ontvangen. Zie link voor de opmaak. |
| Geen referentiecomponenten in bestand aanwezig bij pakket: $1 ($2) | Een pakket moet altijd een referentiecomponennt bevatten. Zie link voor de juiste opmaak. |
| Geen ReferentiecomponentID in bestand aanwezig bij pakket ($1) ($2) | Het pakket mist het veld 'ReferentiecomponentID'. |
| Geen ReferentiecomponentURL in bestand aanwezig bij pakket ($1) ($2) | Het pakket mist het veld 'ReferentiecomponentURL'. |
| Geen geldige ReferentiecomponentURL in bestand aanwezig bij pakket ($1) ($2) | Het veld heeft een ongeldige waarde. De juiste waarde is: http(s)://(www).(domain).(ext)/* |
| Pakketregel was niet gevonden, of is leeg | De waarde mag niet leeg zijn. |
| Pakketstyle was niet gevonden, of is leeg | De waarde mag niet leeg zijn. |
Waarschuwingen[bewerken]
Waarschuwingen stoppen het script niet; maar worden enkel ter informatie getoond. De volgende waarschuwingen zijn mogelijk:
| Melding | Omschrijving |
|---|---|
| Kon view met id: $1 niet genereren | Onze imageserver heeft geen geldige waarde terug gegeven, of de opgegeven View heeft geen juiste waarde. |
| Er is een niet bekend ReferentiecomponentID opgegeven ($1) | Er is een ongeldige of een niet bestaande referentiecomponent id meegeleverd. |
Specificaties voor weergave in Softwarecatalogus[bewerken]
Let op de weergave van de pakketten en referentiecomponeten kent de volgende specificaties:
- Als een softwarepakket een relatie heeft met een referentiecomponent moet deze ook visueel worden weergegeven binnen de betreffende referentiecomponent
- Als er geen relaties is, wordt alleen de referentiecomponent getoond 'as is'.
- De naam van het referentiecomponent wordt boven uitgelijnd ipv in het midden
- Weergave van pakketregel op scherm conform volgend format: <leverancier>:<spatie><naam pakket><spatie><versie pakket><spatie>-<spatie><status pakket>-<spatie><cbs codes van de gebruikende gemeenten>
- Per referentiecomponent is er voor elk softwarepakket één regel beschikbaar.
- Bij standaard referentiecomponent is de inschatting dat er maximaal vijf regels passen. Dit wordt dynamisch bepaald, bv als op platen er ruimte is voor meer regels moet dit ook opgevuld kunnen worden.
- Indien het aantal regels niet meer (leesbaar past) binnen een referentiecomponent wordt er een '*' achter de naam van het referentiecomponent gezet, hetgeen betekent dat er meerdere softwarepakketten zijn. Door te klikken op deze naam wordt de gebruiker naar de achterliggende URL gebracht waarin het totaal overzicht staat.
- Indien de naam van het referentiecomponent te lang is om goed te worden weergegeven in de ruimte die beschikbaar is, worden de naam afgebroken en verschijnen er drie punten '...'. Let op dat er nog ruimte overblijft voor een '*' als er teveel softwareproducten gekoppeld worden
- Indien de pakketregel te lang wordt (afhankelijk van de breedte die beschikbaar is. Worden de onderdelen van deze regel ook afgebroken en vervangen door '...'.
- De afbreking kan plaatsvinden bij Leverancier, Naam pakket of Versie pakket. Status pakket moet altijd volledig getoond worden. Eerste idee is om per onderdeel een percentage te definiëren waarbinnen deze getoond moet worden. Voorbeeld:
- Leverancier:25%
- Naam pakket: 25%
- Versie pakket: 25%
- Status pakket: 10%
- Lijst CBS codes van gemeenten die het pakket gebruiken 15%
Voorbeeld (zonder de CBS codes):
Sandbox[bewerken]
- Test op ViewGenerator de API.
- Test met een TestFormulier
Kies bij View-id in het formulier voor GEMMA Referentiecomponenten om de meest representatieve view te krijgen.