Naar hoofdinhoud gaan

Manifest van een aangepast besturingselement

Schema-id: custom-control-manifest@1 Machineleesbaar schema: custom-control-manifest.schema.json

De canonieke beschrijving van een aangepast besturingselement (in PCF-stijl, sectie 6.3): de Module Federation-remote die de Player van de modelgestuurde app op de plaats van een standaard veldeditor in een formulier of weergave koppelt. Een manifest wordt op dezelfde manier gevalideerd, of het nu wordt geregistreerd via het Beheercentrum, wordt ingediend met een rechtstreekse API-aanroep, door een AI-assistent is gegenereerd of in een oplossingsimport wordt meegenomen — de regel van één validatiepad (sectie 6.7).

Het wordt niet met de hand geschreven. De registratie van een besturingselement is de upload van het pakket dat @parsware/pack heeft gebouwd, en dit manifest wordt samengesteld uit de eigen parsware.json van dat archief (§28). Wat volgt beschrijft de opgeslagen vorm, om een geëxporteerde oplossing te lezen of een zelf gegenereerde te valideren.

Structuur​

VeldTypeVerplichtOpmerkingen
logicalNametekenreeksjaMet uitgeversvoorvoegsel, in kleine letters snake_case (bijv. par_signature_pad). Aan een formulierveld gekoppeld via de eigenschap control van het veld.
displayNametekenreeksjaLeesbare naam die in het veldpalet van de formulierontwerper wordt getoond.
descriptiontekenreeks | nullneeKorte beschrijving die naast het besturingselement wordt getoond.
scopetekenreeksjaDe globale scopenaam van de Module Federation-container (uniek per remote), gelezen uit de mf-manifest.json van de build in plaats van opnieuw getypt.
moduletekenreeksjaHet pad van de beschikbaar gestelde module die de Player laadt (bijv. ./Control). Moet met ./ beginnen. Ook uit de build gelezen.
entryFileNametekenreeksneeHet startbestand van de container in het pakket (bijv. remoteEntry.js). De serveer-URL wordt berekend uit de omgeving, de logische naam en dit veld — er is geen URL om op te slaan. Leeg in Hosted-modus.
packageHashtekenreeks | nullneeSHA-256 in hexadecimale kleine letters van het pakketarchief waaruit het besturingselement is geregistreerd. Bij import gecontroleerd tegen de bytes die in een oplossingspakket zijn meegereisd, zodat wat wordt geserveerd ook is wat is geëxporteerd. Null in Hosted-modus.
remoteEntryUrltekenreeks | nullneeAlleen Hosted-modus: een absolute http(s)-URL naar een extern geserveerde remoteEntry.js, voor hot reload tijdens het schrijven. Registratie ervan wordt geweigerd tenzij de omgeving van het type Development is, en een besturingselement in Hosted-modus reist niet mee in een oplossingspakket — zijn code is niet aan het platform om mee te nemen.
substitutesFortekenreeks[]jaDe besturingstypen van velden waaraan dit besturingselement kan worden gekoppeld: een of meer van Text, MultilineText, Number, Boolean, DateTime, Lookup, File, Image, Custom. Moet ten minste één waarde bevatten. Het veldpalet biedt het besturingselement alleen aan waar het besturingstype van een veld overeenkomt. Dit zijn de families van gegevenstypen waartoe een veld behoort — niet de namen van ingebouwde besturingselementen die een plaatsing op een formulier kiest (TextArea, Toggle, Dropdown, …); dat is een ander vocabulaire dat toevallig vier namen deelt.

Wat het niet meer heeft​

requestedScopes en declaredEntities zijn verdwenen, en additionalProperties is false, dus een manifest dat een van beide nog bevat, wordt geweigerd in plaats van stilletjes genegeerd. Een besturingselement draait met de rechten van de persoon die het gebruikt (§24): een set gevraagde scopes werd altijd al doorsneden met de eigen sessie van de gebruiker, dus die kon de gebruiker van een besturingselement alleen beperken en nooit verruimen, en de lijst met gedeclareerde tabellen werd door geen enkel codepad gelezen. Door beide te schrappen, is het beveiligingsverhaal één zin in plaats van twee knoppen.

Ook een verplichte remoteEntryUrl is verdwenen. De bundel reist nu mee als pakket dat vanaf de eigen origin van het platform wordt geserveerd, dus de URL wordt berekend in plaats van opgeslagen (§28).

Het contract van een besturingselement​

De beschikbaar gestelde module (./Control) is één React-component die het vaste ParswareControlProps-contract uit @parsware/runtime-sdk implementeert:

interface ParswareControlProps {
  value: unknown;                     // the bound field's current value
  onChange: (next: unknown) => void;  // commit a new value back to the form
  fieldMetadata: FieldMetadata;       // the bound field's type/label/constraints
  context: RuntimeContext;            // the same auth/data/logging context apps get
}

De Player levert deze props bij het renderen. Een besturingselement bereikt het platform uitsluitend via context (een ParswareRuntime) — nooit met een rechtstreekse aanroep naar de Gateway of Identity.

Waar het wordt gevalideerd​

  • Registratie — de Application Layer valideert het manifest tegen custom-control-manifest@1 en dwingt af dat logicalName begint met het voorvoegsel van de eigenaar-uitgever, voordat het besturingselement in een omgeving wordt vastgelegd.
  • Oplossingsimport — elk ingesloten manifest in een oplossingspakket wordt opnieuw gevalideerd tegen hetzelfde schema voordat het besturingselement in de doelomgeving wordt geregistreerd.

Beveiligingsopmerkingen​

Een aangepast besturingselement draait in hetzelfde JavaScript-realm als de shell (Module Federation, geen iframe — sectie 6.3), dus de vertrouwensgrens wordt elders afgedwongen:

  • Een verpakt besturingselement wordt geserveerd vanaf de eigen origin van het platform, dus er is geen externe origin om op een allowlist te zetten. De CSP-allowlist bewaakt nog wel de Hosted-modus, de enige vorm waarvan een maker de bundel overal naartoe kan laten wijzen — en die buiten een ontwikkelomgeving wordt geweigerd.
  • Het archief wordt gecontroleerd voordat het wordt opgeslagen: grootte, aantal bestanden, hoe groot het uitgepakt wordt, dat geen enkel item een pad buiten zijn eigen map noemt, en dat elk bestand van een type is dat het platform serveert.
  • Het besturingselement kan alleen worden geladen als een oplossing het in die omgeving heeft uitgerold, en de hash van het pakket wordt bij import gecontroleerd en nogmaals voordat het ooit naar schijf wordt uitgepakt.
  • Elke gegevensaanroep die het doet via de Runtime SDK, wordt aan de serverkant geautoriseerd tegen het App Context Token, dat de eigen scopes van de gebruiker bevat. Een besturingselement kan precies wat de persoon die het gebruikt kan, en geen enkel veld in dit manifest verandert daar iets aan.

Gerelateerd​