Bewerken: JobMaterial (Materiaalregel)

Sectie: Functionaliteit & property-gedrag

Reden:

## Functionaliteit & property-gedrag

Veel JobMaterial-properties worden niet handmatig ingevuld maar door workflows aangemaakt, gevuld of bijgewerkt. Onderstaande paragrafen beschrijven het gedrag van de belangrijkste velden; gebruik `lookup_property_usage("JobMaterial", "<property>")` voor de volledige, actuele lijst workflows per property en `lookup_workflow("<naam>")` voor de XML.

- **Aanmaken van de regel (`Id`, `Article`, `Status`)** — Een JobMaterial-regel wordt op vier manieren aangemaakt: handmatig via de UI, vanuit de mobiele app (`Mobile_Article_AddJobMaterial`), vanuit een magazijnuitgifte (`WarehouseServeOutline_CreateJobMaterial`) of als splitsregel bij picklijstverwerking (`PickList_SplitJobMaterial`). `Mobile_Article_AddJobMaterial` start met een `Insert`, zet direct `Article`, `Customer` (overgenomen van de job) en `Price` (opgehaald via `Article_GetPurchasePrice`) en roept aansluitend `JobMaterial_SetInternalChargeValues` aan voor doorbelastingsopbouw. `WarehouseServeOutline_CreateJobMaterial` maakt de regel aan vanuit een uitgifte-document en vult ook `BookDate`, `Warehouse`, `WarehouseLocation` en `QuantityOut` in één transactie. Consultanttip: bij magazijnuitgifte-gedreven regels zijn `QuantityOut` en `BookDate` al ingevuld bij aanmaak; bij handmatige of mobiele regels moet de uitgifte nog volgen.

- **Defaults & kostendragers (`Warehouse`, `WarehouseLocation`, `Price`, `CostCenter`, `CostType`)** — `JobMaterial_SetDefaults` bepaalt het standaard magazijn en de magazijnlocatie op basis van het artikel en de vestiging van de job (inclusief een dialoog als `StockLevelPerSite` actief is). `JobMaterial_UpdateMaterialCost` roept intern `JobMaterial_TakeOverExpenseCarriersFromJob` aan, die via `AssignWhenEmpty` de kostenplaats, kostensoort, klant, afdeling, equipment, procesfunctie, project en vakgroep overpakt van de bovenliggende job — maar alleen als de regel die velden nog leeg heeft. Dit mechanisme zorgt dat kosten standaard op de juiste dragers landen zonder dat de medewerker deze handmatig hoeft in te vullen. De `Price` wordt gezet door `JobMaterial_ReserveArticle` en `JobMaterial_SetDefaults` via `Article_GetPurchasePrice`; later kan `PriceMutationLine_UpdateJobMaterial` de prijs corrigeren bij een prijsmutatie.

- **Reservering (`ReservedQuantity`, `ArticleReserved`)** — Het reserveringsmechanisme loopt via `JobMaterial_ReserveArticle`: zodra `ArticleReserved` op `True` staat én `ReservedQuantity` nog 0 is, wordt `Article_Reserve` aangeroepen met `PlannedQuantity` als te reserveren hoeveelheid. `JobMaterial_AdjustReservation` past de reservering aan bij een hoeveelheidswijziging; `JobMaterial_ClearReservation` maakt de reservering vrij. Bij het verwijderen van de regel (`JobMaterial_PreTrash`) wordt automatisch de reservering vrijgegeven. `ActionField376` leest én schrijft zowel `ArticleReserved` als `ReservedQuantity` — typisch de actie "Reserveer materiaal" op het job-scherm. Consultanttip: annuleer je een goedgekeurde regel met openstaande reservering maar zonder verbruik, dan handelt `JobMaterial_PostApprove` de vrijgave af via `JobMaterial_ClearReservation`.

- **Picklijst-splitsing (`PickedQuantity`, `PlannedQuantity`, `ReservedQuantity`)** — Wanneer een picklijst slechts een deel van de geplande hoeveelheid pickt, splitst `PickList_SplitJobMaterial` de originele regel: er wordt een nieuwe JobMaterial aangemaakt (kopie van de originele), `PickedQuantity` en `QuantityOut` worden op de originele regel bevroren op de gepickte hoeveelheid, en het resterend verschil (planned − picked, reserved − picked) gaat naar de nieuwe splitsregel. `PickListLine_PreProcess` schrijft vervolgens `PickedQuantity`, `Warehouse`, `WarehouseLocation` en `QuantityOut` terug op de gekoppelde JobMaterial-regel. `PickListLine_SplitJobMaterialIfNeeded` bewaakt of splitsing nodig is vóór goedkeuring van een picklistline.

- **Uitgifte via magazijn (`QuantityOut`, `QuantityIn`, `WarehouseServeOutline`, `BookDate`)** — Magazijnuitgifte vindt plaats via een WarehouseServeOut-document. `WarehouseServeOutline_UpdateJobMaterial` schrijft na goedkeuring de definitieve `QuantityOut`, `QuantityIn`, `Price`, `BookDate`, `ChargeRaisePercentage` en `InvoiceQuantity` terug op de materiaalregel, en koppelt de `WarehouseServeOutline`-referentie. Bij `JobMaterial_PostApprove` wordt, als `WarehouseServeOutline` gevuld is, de bijbehorende WarehouseServeOut automatisch goedgekeurd (instelbaar via `Settings.JobMaterial.ApproveWarehouseServeOut`) en de reservering verwerkt via `JobMaterial_ProcessArticleReservation`. Dit berekent de werkelijk onttrokken hoeveelheid (QuantityOut − QuantityIn, gemaximeerd op ReservedQuantity) en verlaagt de voorraadreservering dienovereenkomstig.

- **Goedkeuring & status (`Status`, `JobMaterial_PostApprove`)** — De statusovergang naar `Goedgekeurd` (2) wordt bewaakt door `JobMaterial_PostApprove` (ChangeStatus-workflow). Naast het verwerken van de reservering voegt deze workflow ook het artikel toe aan de stuklijst van het equipment (`JobMaterial_AddArticleToBillOfMaterials`) als de job en het artikel daarvoor geconfigureerd zijn. `Mobile_JobMaterial_SetAndApproveMaterial` combineert het instellen van hoeveelheden met een directe statuswijziging naar Goedgekeurd in één mobiele actie. `WarehouseServeOut_PostImport` en `WarehouseServeOutline_PostApprove` kunnen ook de status via import of bulkgoedkeuring zetten.

- **Voortgang materiaalstatus op de job (`ArticleReserved`, `ReservedQuantity`, `PickedQuantity`)** — De workflows `Job_UseStockProgressStatus_DetermineCompletelyPicked`, `Job_UseStockProgressStatus_DetermineWaitingForMaterial` en `Job_UseStockProgressStatus_GetReservedJobMaterial` lezen de JobMaterial-regels om te bepalen of alle materialen gereserveerd, gepickt of beschikbaar zijn. Als alle regels volledig gepickt zijn, schakelt `Job_UseStockProgressStatus_DetermineCompletelyPicked` de progressstatus van de job naar `ProgressStatusIdMaterialPicked`. Dit stuurt de "wachten op materiaal"-voortgangsstatus op de job aan, relevant bij instellingen met `UseStockProgressStatus = True`.

> Het volledige, gegenereerde overzicht van álle JobMaterial-properties met hun schrijvende/lezende/filterende workflows staat in [[reference/properties/JobMaterial]].

---