@topconsultnpm/sdkui-react 6.22.0-dev3.3 → 6.22.0-dev3.31

package/lib/hooks/useInputDialog.d.ts

@@ -1,3 +1,4 @@
+import React from "react";
 import { FileDescriptor, FileFormats } from '@topconsultnpm/sdk-ts';
 export declare const useInputCvtFormatDialog: () => [() => Promise<FileFormats>, () => JSX.Element];
 export declare const useFileDialog: () => {
@@ -5,7 +6,7 @@ export declare const useFileDialog: () => {
 };
 export declare const useInputAttachmentsDialog: () => {
     openConfirmAttachmentsDialog: (list: FileDescriptor[]) => Promise<string[] | undefined>;
-    ConfirmAttachmentsDialog: () => import("react/jsx-runtime").JSX.Element | null;
+    ConfirmAttachmentsDialog: () => React.JSX.Element | null;
 };
 export type FileSourceType = 'filesystem' | 'scanner-new' | 'scanner-edit' | undefined;
 export declare const useFileSourceDialog: () => [(hasExistingFile?: boolean) => Promise<FileSourceType>, () => JSX.Element];

package/lib/hooks/useMultiMasterDetailDcmts.d.ts

@@ -16,19 +16,6 @@ export type MidValue = {
     mid: number;
     value: string;
 };
-/** Stato del wait panel: le chiavi sono quelle dei props di TMLayoutWaitingContainer */
-export type WaitPanelState = {
-    showWaitPanel: boolean;
-    waitPanelTitle: string;
-    showWaitPanelPrimary: boolean;
-    waitPanelTextPrimary: string;
-    waitPanelValuePrimary: number;
-    waitPanelMaxValuePrimary: number;
-    showWaitPanelSecondary: boolean;
-    waitPanelTextSecondary: string;
-    waitPanelValueSecondary: number;
-    waitPanelMaxValueSecondary: number;
-};
 interface UseMultiMasterDetailDcmtsParams {
     /** Tipo documento del master */
     dtd: DcmtTypeDescriptor;
@@ -108,6 +95,4 @@ export declare const useMultiMasterDetailDcmts: ({ dtd, masterDcmt, onClose, can
     setStopOnFirstError: import("react").Dispatch<import("react").SetStateAction<boolean>>;
     isArchiving: boolean;
     archiveAllAsync: () => Promise<void>;
-    waitPanel: WaitPanelState;
-    abortController: AbortController | undefined;
 };

package/lib/hooks/useMultiMasterDetailDcmts.js

@@ -2,9 +2,10 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { AccessLevels, ArchiveConstraints, ArchiveEngineByID, DcmtOpers, GeneralRetrieveFormats, MetadataDataDomains, MetadataDataTypes, RelationCacheService, RelationTypes, ResultTypes, RetrieveFileOptions, SDK_Globals, SystemMIDsAsNumber } from '@topconsultnpm/sdk-ts';
 import { MetadataValueDescriptorEx } from '../ts';
 import { clearMultiDetailLayout, Globalization, getExceptionMessage, getMultiDetailSectionsOpen, handleArchiveVisibility, hasMultiDetailLayout, saveMultiDetailSectionsOpen, SDKUI_Localizator } from '../helper';
-import { getDcmtMetadataByMid, getUserMetadataSorted, mapAssociationsFromMetadata } from '../helper/dcmtsHelper';
+import { canViewMetadata, getDcmtMetadataByMid, getUserMetadataSorted, mapAssociationsFromMetadata } from '../helper/dcmtsHelper';
 import { ButtonNames, TMExceptionBoxManager, TMMessageBoxManager } from '../components/base/TMPopUp';
 import TMSpinner from '../components/base/TMSpinner';
+import { TMWaitPanelManager } from '../components/base/waitPanel';
 import ShowAlert from '../components/base/TMAlert';
 import { TMResultManager } from '../components/forms/TMResultDialog';
 import { useDataListItem } from './useDataListItem';
@@ -17,18 +18,6 @@ export var MultiDetailArchivePhase;
     /** Riepilogo delle archiviazioni */
     MultiDetailArchivePhase[MultiDetailArchivePhase["ArchiveSummary"] = 1] = "ArchiveSummary";
 })(MultiDetailArchivePhase || (MultiDetailArchivePhase = {}));
-const CLOSED_WAIT_PANEL = {
-    showWaitPanel: false,
-    waitPanelTitle: '',
-    showWaitPanelPrimary: false,
-    waitPanelTextPrimary: '',
-    waitPanelValuePrimary: 0,
-    waitPanelMaxValuePrimary: 0,
-    showWaitPanelSecondary: false,
-    waitPanelTextSecondary: '',
-    waitPanelValueSecondary: 0,
-    waitPanelMaxValueSecondary: 0,
-};
 /**
  * Logica dell'archiviazione multipla dei dettagli: relazioni, sezioni, righe del riepilogo e
  * archiviazione. Il rendering sta in TMMultiMasterDetailDcmtsForm
@@ -76,12 +65,11 @@ export const useMultiMasterDetailDcmts = ({ dtd, masterDcmt, onClose, canNavigat
     // Archiviazione finale
     const [stopOnFirstError, setStopOnFirstError] = useState(true);
     const [isArchiving, setIsArchiving] = useState(false);
-    const [waitPanel, setWaitPanel] = useState(CLOSED_WAIT_PANEL);
-    const abortControllerRef = useRef(undefined);
     const selectedItem = detailRelationItems.find(item => item.relation === selectedRelation);
     const hasMultipleTypes = detailRelationItems.length > 1;
     const canUpdateMaster = canUpdateMasterCallback(dtd, masterDcmt);
-    const masterFieldsCount = useMemo(() => getUserMetadataSorted(dtd).length, [dtd]);
+    // Stessi metadati delle card del master (vedi TMMasterInfoFields): quelli non visibili non contano
+    const masterFieldsCount = useMemo(() => getUserMetadataSorted(dtd).filter(canViewMetadata).length, [dtd]);
     // Nel riepilogo si mostrano solo le righe del tipo selezionato
     const currentRows = useMemo(() => archiveRows.filter(r => r.__tid === selectedRelation?.detailTID), [archiveRows, selectedRelation?.detailTID]);
     const archivedDetailsCount = archivedDetailResults.reduce((total, r) => total + (r.dcmtsFound ?? r.jsonResult?.length ?? 0), 0);
@@ -619,44 +607,68 @@ export const useMultiMasterDetailDcmts = ({ dtd, masterDcmt, onClose, canNavigat
                 dataTypeByMid.set(md.id, md.dataType); });
             // Collegamenti della relazione valorizzati dal master (prevalgono sui valori del form)
             const associationMids = await getMasterAssociationsForDetailAsync(selectedRelation);
-            // Barra primaria: avanzamento documenti. Barra secondaria: upload del file corrente
-            const abortController = new AbortController();
-            abortControllerRef.current = abortController;
-            setWaitPanel({
-                ...CLOSED_WAIT_PANEL,
-                showWaitPanel: true,
-                waitPanelTitle: SDKUI_Localizator.Archiving,
-                showWaitPanelPrimary: rowsToArchive.length > 1,
-                waitPanelMaxValuePrimary: rowsToArchive.length,
-                showWaitPanelSecondary: true,
+            // Con piu' righe: primaria sui documenti, secondaria sui byte. Con una riga sola solo i byte.
+            const isBatch = rowsToArchive.length > 1;
+            const waitPanel = TMWaitPanelManager.show({
+                title: SDKUI_Localizator.Archiving,
+                max: isBatch ? rowsToArchive.length : 0,
+                cancelable: true,
+                showSecondary: isBatch,
+                showCounters: isBatch,
+                primaryLabel: isBatch ? SDKUI_Localizator.Documents : undefined,
+                secondaryLabel: isBatch ? 'File corrente' : undefined,
             });
+            const publishBytes = (loaded, total) => {
+                const text = total > 0
+                    ? `Uploading... ${Globalization.getNumberDisplayValue(loaded, true)} / ${Globalization.getNumberDisplayValue(total, true)}`
+                    : '';
+                if (isBatch)
+                    waitPanel.setSecondary({ value: loaded, max: total, text });
+                else
+                    waitPanel.update({ value: loaded, max: total, subtitle: text });
+            };
             const result = [];
             const archivedRowIds = new Set();
-            for (let i = 0; i < rowsToArchive.length; i++) {
-                if (abortController.signal.aborted) {
-                    result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.WARNING, description: `Operazione interrotta. Elaborati ${i} documenti` });
-                    break;
-                }
-                const rowData = rowsToArchive[i];
-                try {
-                    setWaitPanel(prev => ({ ...prev, waitPanelTextPrimary: `${SDKUI_Localizator.Archiving} ${i + 1} / ${rowsToArchive.length}` }));
-                    const newDID = await archiveRowAsync(rowData, detailTID, dataTypeByMid, associationMids, abortController.signal);
-                    setWaitPanel(prev => ({ ...prev, waitPanelValuePrimary: i + 1 }));
-                    archivedRowIds.add(rowData.id);
-                    result.push({ rowIndex: i, id1: detailTID, id2: newDID, resultType: ResultTypes.SUCCESS });
-                }
-                catch (error) {
-                    const err = error;
-                    // Annullamento richiesto dall'utente: interrompe senza mostrare l'errore
-                    if (err?.name === 'CanceledError' || abortController.signal.aborted) {
+            try {
+                for (let i = 0; i < rowsToArchive.length; i++) {
+                    // Con la conferma di interruzione aperta il loop resta in pausa qui
+                    await waitPanel.waitWhilePaused();
+                    if (waitPanel.aborted) {
                         result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.WARNING, description: `Operazione interrotta. Elaborati ${i} documenti` });
+                        waitPanel.warning();
                         break;
                     }
-                    result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.ERROR, description: getExceptionMessage(error) });
-                    if (stopOnFirstError)
-                        break;
+                    if (isBatch)
+                        waitPanel.setSubtitle(`${SDKUI_Localizator.Archiving} ${i + 1} / ${rowsToArchive.length}`);
+                    const rowData = rowsToArchive[i];
+                    try {
+                        const newDID = await archiveRowAsync(rowData, detailTID, dataTypeByMid, associationMids, waitPanel.signal, publishBytes);
+                        archivedRowIds.add(rowData.id);
+                        result.push({ rowIndex: i, id1: detailTID, id2: newDID, resultType: ResultTypes.SUCCESS });
+                        waitPanel.ok();
+                    }
+                    catch (error) {
+                        const err = error;
+                        // Annullamento richiesto dall'utente: interrompe senza mostrare l'errore
+                        if (err?.name === 'CanceledError' || waitPanel.aborted) {
+                            result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.WARNING, description: `Operazione interrotta. Elaborati ${i} documenti` });
+                            waitPanel.warning();
+                            break;
+                        }
+                        result.push({ rowIndex: i, id1: detailTID, id2: undefined, resultType: ResultTypes.ERROR, description: getExceptionMessage(error) });
+                        waitPanel.error();
+                        if (stopOnFirstError)
+                            break;
+                    }
+                    // Avanza a elaborazione conclusa: la barra non arriva al 100% prima dell'ultimo documento
+                    if (isBatch)
+                        await waitPanel.step();
                 }
             }
+            finally {
+                // Chiuso prima del riepilogo dei risultati
+                waitPanel.close();
+            }
             // Le righe archiviate escono dal riepilogo
             if (archivedRowIds.size > 0) {
                 setArchiveRows(prev => prev.filter(r => !archivedRowIds.has(r.id)));
@@ -676,13 +688,11 @@ export const useMultiMasterDetailDcmts = ({ dtd, masterDcmt, onClose, canNavigat
             TMExceptionBoxManager.show({ exception: error });
         }
         finally {
-            abortControllerRef.current = undefined;
-            setWaitPanel(CLOSED_WAIT_PANEL);
             setIsArchiving(false);
         }
     };
-    // Archiviazione di una singola riga, con avanzamento dell'upload sulla barra secondaria
-    const archiveRowAsync = async (row, detailTID, dataTypeByMid, associationMids, signal) => {
+    // Archiviazione di una singola riga, con avanzamento dell'upload notificato a onBytes
+    const archiveRowAsync = async (row, detailTID, dataTypeByMid, associationMids, signal, onBytes) => {
         const ae = new ArchiveEngineByID(SDK_Globals.tmSession);
         ae.TID = detailTID;
         ae.Metadata_ClearAll();
@@ -714,23 +724,12 @@ export const useMultiMasterDetailDcmts = ({ dtd, masterDcmt, onClose, canNavigat
         });
         if (row.__file)
             ae.ArchivingFile = row.__file;
-        let firstBlock = true;
-        let maxFileSize = 0;
         return ae.ArchiveAsync(signal, (pd) => {
-            if (firstBlock) {
-                maxFileSize = pd.ProgressBarMaximum ?? 0;
-                setWaitPanel(prev => ({ ...prev, waitPanelMaxValueSecondary: maxFileSize }));
-                firstBlock = false;
-            }
-            setWaitPanel(prev => ({
-                ...prev,
-                waitPanelValueSecondary: pd.ProgressBarValue,
-                waitPanelTextSecondary: `Uploading... ${Globalization.getNumberDisplayValue(pd.ProgressBarValue, true)} / ${Globalization.getNumberDisplayValue(maxFileSize, true)}`,
-            }));
-            if (pd.ProgressBarValue === pd.ProgressBarMaximum) {
-                setWaitPanel(prev => ({ ...prev, waitPanelValueSecondary: 0, waitPanelMaxValueSecondary: 0, waitPanelTextSecondary: '' }));
-                firstBlock = true;
-            }
+            // Upload completato: la barra si azzera per il file successivo
+            if (pd.ProgressBarValue === pd.ProgressBarMaximum)
+                onBytes(0, 0);
+            else
+                onBytes(pd.ProgressBarValue ?? 0, pd.ProgressBarMaximum ?? 0);
         });
     };
     return {
@@ -755,6 +754,5 @@ export const useMultiMasterDetailDcmts = ({ dtd, masterDcmt, onClose, canNavigat
         openAddForm, openEditForm, closeAddForm, deleteRow, duplicateRow, upsertRow, updateRowValues, copyArchivedDetailToRows,
         // Archiviazione
         stopOnFirstError, setStopOnFirstError, isArchiving, archiveAllAsync,
-        waitPanel, abortController: abortControllerRef.current,
     };
 };

package/lib/hooks/usePreventFileDrop.js

@@ -2,7 +2,12 @@ import { useEffect } from "react";
 const usePreventFileDrop = (allowedDropZones) => {
     useEffect(() => {
         const isOverAllowedZone = (event) => allowedDropZones.some((ref) => ref.current?.contains(event.target));
+        // Il blocco vale solo per i file trascinati da fuori: i drag interni all'applicazione
+        // (riordino di metadati, colonne, tab, ...) devono restare liberi di completarsi
+        const isFileDrag = (event) => event.dataTransfer?.types?.includes("Files") === true;
         const handleDragOver = (event) => {
+            if (!isFileDrag(event))
+                return;
             if (isOverAllowedZone(event)) {
                 // Riafferma "copy" ad ogni dragover: altrimenti un "none"
                 // impostato mentre si era fuori zona resta e mostra "not-allowed"
@@ -17,6 +22,8 @@ const usePreventFileDrop = (allowedDropZones) => {
             }
         };
         const handleDragEnter = (event) => {
+            if (!isFileDrag(event))
+                return;
             if (isOverAllowedZone(event)) {
                 document.body.style.cursor = "default";
             }
@@ -28,6 +35,8 @@ const usePreventFileDrop = (allowedDropZones) => {
             document.body.style.cursor = "default";
         };
         const handleDrop = (event) => {
+            if (!isFileDrag(event))
+                return;
             if (!isOverAllowedZone(event)) {
                 event.preventDefault();
                 document.body.style.cursor = "default";

package/lib/hooks/useWorkflowApprove.js

@@ -1,5 +1,25 @@
 import { useState, useEffect, useCallback } from 'react';
 import { SDK_Globals } from '@topconsultnpm/sdk-ts';
+const WORKFLOW_APPROVE_CHANGED_EVENT = 'onWorkflowApproveChange';
+/** Totale dei documenti da approvare: somma dei dcmtsFound delle singole categorie. */
+const calcTotalDcmtsFound = (data) => {
+    return data.reduce((sum, item) => sum + (item.dcmtsFound || 0), 0);
+};
+/**
+ * Fetch in corso.
+ *
+ * La WFAppr non porta un contatore ma l'intera lista di approvazione con le righe
+ * dei documenti, ed è chiesta da più istanze del hook a ridosso l'una dell'altra
+ * (coda del login, pagina di approvazione, widget della home). Chi arriva mentre
+ * è già in volo aspetta la stessa risposta invece di aprire una seconda richiesta.
+ */
+let inFlight;
+/** Ricarica i dati e notifica tutte le istanze del hook. */
+const load = async () => {
+    const result = await SDK_Globals.tmSession?.NewWorkflowEngine().WFApprAsync(1);
+    SDK_Globals.currentWorkflowApproveData = result ?? [];
+    window.dispatchEvent(new CustomEvent(WORKFLOW_APPROVE_CHANGED_EVENT));
+};
 /**
  * Hook per gestire i dati di approvazione del workflow.
  * Fornisce il dataSource, lo stato di caricamento e una funzione per aggiornare i dati.
@@ -7,13 +27,10 @@ import { SDK_Globals } from '@topconsultnpm/sdk-ts';
 export const useWorkflowApprove = () => {
     const [workflowApproveData, setWorkflowApproveData] = useState(SDK_Globals.currentWorkflowApproveData);
     const [isLoading, setIsLoading] = useState(false);
-    const [totalDcmtsFound, setTotalDcmtsFound] = useState(0);
-    /**
-     * Calcola il numero totale di dcmtsFound dai dati del workflow.
-     */
-    const calculateTotalDcmtsFound = useCallback((data) => {
-        return data.reduce((sum, item) => sum + (item.dcmtsFound || 0), 0);
-    }, []);
+    // Seminato dai dati già in cache: un'istanza montata a login concluso parte dal
+    // totale reale e non da zero, altrimenti chi confronta questo valore con il
+    // contatore della home vede una differenza inesistente e ricarica a vuoto.
+    const [totalDcmtsFound, setTotalDcmtsFound] = useState(() => calcTotalDcmtsFound(SDK_Globals.currentWorkflowApproveData));
     /**
      * Ottiene tutti i work items che corrispondono a un determinato DID.
      * Restituisce un array di oggetti { tid, did }.
@@ -40,12 +57,10 @@ export const useWorkflowApprove = () => {
         }
         setIsLoading(true);
         try {
-            const result = await SDK_Globals.tmSession.NewWorkflowEngine().WFApprAsync(1);
-            SDK_Globals.currentWorkflowApproveData = result ?? [];
-            // Aggiorna anche il totale dei dcmtsFound
-            setTotalDcmtsFound(calculateTotalDcmtsFound(SDK_Globals.currentWorkflowApproveData));
-            // Notifica tutte le istanze del hook che i dati sono cambiati.
-            window.dispatchEvent(new CustomEvent('onWorkflowApproveChange'));
+            if (!inFlight) {
+                inFlight = load().finally(() => { inFlight = undefined; });
+            }
+            await inFlight;
         }
         catch (error) {
             console.error("Errore durante il fetch dei dati di approvazione workflow:", error);
@@ -53,18 +68,19 @@ export const useWorkflowApprove = () => {
         finally {
             setIsLoading(false);
         }
-    }, [calculateTotalDcmtsFound]); // useCallback con array vuoto perché non ha dipendenze esterne a React
+    }, []);
     // Questo useEffect serve a sincronizzare lo stato tra diverse istanze del hook.
     // Se il componente A chiama refreshWorkflowApprove, il componente B (che usa lo stesso hook)
     // riceverà l'evento e aggiornerà il suo stato locale.
     useEffect(() => {
         const handleUpdate = () => {
             setWorkflowApproveData(SDK_Globals.currentWorkflowApproveData);
+            setTotalDcmtsFound(calcTotalDcmtsFound(SDK_Globals.currentWorkflowApproveData));
         };
-        window.addEventListener('onWorkflowApproveChange', handleUpdate);
+        window.addEventListener(WORKFLOW_APPROVE_CHANGED_EVENT, handleUpdate);
         return () => {
-            window.removeEventListener('onWorkflowApproveChange', handleUpdate);
+            window.removeEventListener(WORKFLOW_APPROVE_CHANGED_EVENT, handleUpdate);
         };
-    }, [calculateTotalDcmtsFound]);
+    }, []);
     return { workflowApproveData, isLoading, refreshWorkflowApprove, totalDcmtsFound, getWorkItemsByDID };
 };

package/lib/services/caseflow/CaseFlowService.d.ts

@@ -103,6 +103,17 @@ export declare class CaseFlowService {
      * @returns id della nuova istanza.
      */
     static CreateCaseFlowInstance(template: CaseFlowTemplateDescriptor, instanceName: string, instanceDescription: string | undefined, metadataValues: Record<number, string>): Promise<number>;
+    /**
+     * Avvia un'istanza tramite StartAsync(cftid, id): il backend porta la pratica
+     * da `New` a `InProgress` e materializza i workitem della prima azione.
+     *
+     * NON va chiamata dopo `CreateCaseFlowInstance`: la Create dell'API REST
+     * esegue già lo start internamente, quindi un'istanza appena creata è
+     * ancora `New` solo nel descrittore inviato, non lato server. Questa resta
+     * per le istanze che si trovano davvero in `New` (avvio differito); sulle
+     * altre il backend rifiuta.
+     */
+    static startCaseflow(caseFlowId: number, cftid?: number): Promise<void>;
     /**
      * Elimina un'istanza tramite DeleteAsync(cftid, id). Il cftid è preso dal
      * template fornito (se disponibile) oppure risolto dall'istanza.
@@ -190,11 +201,10 @@ export declare class CaseFlowService {
     /**
      * Stato "l'utente corrente segue questa pratica" letto dal descrittore.
      *
-     * Restituisce `undefined` quando il descrittore non porta l'informazione —
-     * cioè SEMPRE, finché il backend non aggiunge `IsFollow` in output a
-     * `usp_Cfi_RetrieveAll`/`usp_Cfi_Retrieve` e la relativa proprietà al
-     * contratto. Il tipo è tollerante perché la colonna è un BIT/NUMBER e può
-     * arrivare come booleano, come 0/1 o come stringa.
+     * `isFollow` fa ormai parte del contratto (`CaseFlowInstanceDescriptor`):
+     * arriva valorizzato da `usp_Cfi_RetrieveAll`/`usp_Cfi_Retrieve`. Resta
+     * `undefined` solo quando il descrittore proviene da una sorgente che non
+     * popola il campo.
      *
      * Da NON dedurre dalla bacheca Home come fanno pratiche-dossier e gruppi di
      * lavoro (filtro su `HomeBlogPost.classID`): quella query prende `TOP 30`
@@ -213,7 +223,27 @@ export declare class CaseFlowService {
     static completeDataCompletionWorkItem(caseFlowId: number, workItemId: number, metadataValues: Record<number, string>, response?: string, cftid?: number): Promise<void>;
     /** Rifiuta un workitem. Il motivo viene pubblicato in bacheca dal backend. */
     static rejectWorkItem(caseFlowId: number, workItemId: number, response?: string, cftid?: number): Promise<void>;
-    /** Assegna un'azione a un utente creando il relativo workitem (operazione Assign). */
+    /**
+     * Prende in carico un'azione per se stessi (operazione Claim): il backend
+     * crea il workitem intestato al chiamante e porta l'azione in lavorazione.
+     *
+     * Non e' un caso particolare di `createWorkItemForAction`: assegnare e'
+     * riservato a Owner e Supervisore, prendere in carico e' di chiunque lavori
+     * alla pratica. Passando dall'operazione Assign, un Partecipante si vedeva
+     * rifiutare la presa in carico (TMC-2789).
+     */
+    static claimAction(caseFlowId: number, actionID: number, cftid?: number): Promise<void>;
+    /**
+     * Rilascia un workitem preso in carico (operazione ReleaseClaim): il backend
+     * lo cancella e, se per quell'azione non restano altri destinatari, la riporta
+     * disponibile per la presa in carico.
+     *
+     * Stessa chiamata per due gesti diversi, e' la guardia della SP a distinguerli:
+     * il detentore rilascia il proprio workitem, un Owner/Supervisore annulla
+     * l'assegnazione di un altro. Chi chiama non deve dire quale dei due sta facendo.
+     */
+    static releaseClaim(caseFlowId: number, workItemId: number, cftid?: number): Promise<void>;
+    /** Assegna un'azione a un ALTRO utente creando il relativo workitem (operazione Assign). */
     static createWorkItemForAction(caseFlowId: number, actionID: number, toUserID: number, description?: string, cftid?: number): Promise<void>;
     /** Forza il completamento di un'azione (supervisor). */
     static forceCompleteAction(caseFlowId: number, actionID: number, reason?: string, cftid?: number): Promise<void>;

package/lib/services/caseflow/CaseFlowService.js

@@ -221,6 +221,25 @@ export class CaseFlowService {
         const id = await engine.CreateAsync(d);
         return id ?? 0;
     }
+    /**
+     * Avvia un'istanza tramite StartAsync(cftid, id): il backend porta la pratica
+     * da `New` a `InProgress` e materializza i workitem della prima azione.
+     *
+     * NON va chiamata dopo `CreateCaseFlowInstance`: la Create dell'API REST
+     * esegue già lo start internamente, quindi un'istanza appena creata è
+     * ancora `New` solo nel descrittore inviato, non lato server. Questa resta
+     * per le istanze che si trovano davvero in `New` (avvio differito); sulle
+     * altre il backend rifiuta.
+     */
+    static async startCaseflow(caseFlowId, cftid) {
+        const engine = SDK_Globals.tmSession?.NewCaseFlowInstanceEngine();
+        if (!engine)
+            throw new Error('Motore delle istanze CaseFlow non disponibile.');
+        const resolvedCftid = cftid ?? (await this.getCaseflow(caseFlowId))?.cftid;
+        if (resolvedCftid == null)
+            throw new Error(`Impossibile risolvere il template (cftid) per l'istanza id=${caseFlowId}.`);
+        await engine.StartAsync(resolvedCftid, caseFlowId);
+    }
     /**
      * Elimina un'istanza tramite DeleteAsync(cftid, id). Il cftid è preso dal
      * template fornito (se disponibile) oppure risolto dall'istanza.
@@ -490,11 +509,10 @@ export class CaseFlowService {
     /**
      * Stato "l'utente corrente segue questa pratica" letto dal descrittore.
      *
-     * Restituisce `undefined` quando il descrittore non porta l'informazione —
-     * cioè SEMPRE, finché il backend non aggiunge `IsFollow` in output a
-     * `usp_Cfi_RetrieveAll`/`usp_Cfi_Retrieve` e la relativa proprietà al
-     * contratto. Il tipo è tollerante perché la colonna è un BIT/NUMBER e può
-     * arrivare come booleano, come 0/1 o come stringa.
+     * `isFollow` fa ormai parte del contratto (`CaseFlowInstanceDescriptor`):
+     * arriva valorizzato da `usp_Cfi_RetrieveAll`/`usp_Cfi_Retrieve`. Resta
+     * `undefined` solo quando il descrittore proviene da una sorgente che non
+     * popola il campo.
      *
      * Da NON dedurre dalla bacheca Home come fanno pratiche-dossier e gruppi di
      * lavoro (filtro su `HomeBlogPost.classID`): quella query prende `TOP 30`
@@ -503,14 +521,7 @@ export class CaseFlowService {
      * poi, non esiste nemmeno un ramo nella UNION.
      */
     static readFollowFlag(cf) {
-        const raw = cf.isFollow;
-        if (typeof raw === 'boolean')
-            return raw;
-        if (typeof raw === 'number')
-            return raw !== 0;
-        if (raw === '0' || raw === '1')
-            return raw === '1';
-        return undefined;
+        return cf.isFollow;
     }
     // ----- Workitem: movimentazione del flusso -------------------------------
     //
@@ -551,7 +562,37 @@ export class CaseFlowService {
             comment: response,
         }), cftid);
     }
-    /** Assegna un'azione a un utente creando il relativo workitem (operazione Assign). */
+    /**
+     * Prende in carico un'azione per se stessi (operazione Claim): il backend
+     * crea il workitem intestato al chiamante e porta l'azione in lavorazione.
+     *
+     * Non e' un caso particolare di `createWorkItemForAction`: assegnare e'
+     * riservato a Owner e Supervisore, prendere in carico e' di chiunque lavori
+     * alla pratica. Passando dall'operazione Assign, un Partecipante si vedeva
+     * rifiutare la presa in carico (TMC-2789).
+     */
+    static async claimAction(caseFlowId, actionID, cftid) {
+        await this.executeWorkItemOperation(caseFlowId, CaseFlowWIOperationDescriptor.fromJS({
+            operation: CF_WIOperations.Claim,
+            actionID,
+        }), cftid);
+    }
+    /**
+     * Rilascia un workitem preso in carico (operazione ReleaseClaim): il backend
+     * lo cancella e, se per quell'azione non restano altri destinatari, la riporta
+     * disponibile per la presa in carico.
+     *
+     * Stessa chiamata per due gesti diversi, e' la guardia della SP a distinguerli:
+     * il detentore rilascia il proprio workitem, un Owner/Supervisore annulla
+     * l'assegnazione di un altro. Chi chiama non deve dire quale dei due sta facendo.
+     */
+    static async releaseClaim(caseFlowId, workItemId, cftid) {
+        await this.executeWorkItemOperation(caseFlowId, CaseFlowWIOperationDescriptor.fromJS({
+            operation: CF_WIOperations.ReleaseClaim,
+            wiid: workItemId,
+        }), cftid);
+    }
+    /** Assegna un'azione a un ALTRO utente creando il relativo workitem (operazione Assign). */
     static async createWorkItemForAction(caseFlowId, actionID, toUserID, description, cftid) {
         await this.executeWorkItemOperation(caseFlowId, CaseFlowWIOperationDescriptor.fromJS({
             operation: CF_WIOperations.Assign,

package/lib/services/platform_services.d.ts

@@ -1,3 +1,4 @@
+import React from "react";
 import { JobTypes, ObjectClasses, ProcessDescriptor, DcmtTypeDescriptor } from "@topconsultnpm/sdk-ts";
 export declare class PlatformObjectService {
     static readonly retrieveAllAsync: (objClass: ObjectClasses, refreshCache?: boolean) => Promise<import("@topconsultnpm/sdk-ts").AreaDescriptor[] | import("@topconsultnpm/sdk-ts").NotificationDescriptor[] | import("@topconsultnpm/sdk-ts").RelationDescriptor[] | import("@topconsultnpm/sdk-ts").TaskDescriptor[] | import("@topconsultnpm/sdk-ts").WorkingGroupDescriptor[] | undefined>;
@@ -13,6 +14,6 @@ export declare class PlatformObjectService {
     static readonly createAsync: (objClass: ObjectClasses, jobType: JobTypes, d: any) => Promise<number | undefined>;
     static readonly deleteAsync: (objClass: ObjectClasses, id: number) => Promise<number | undefined>;
     static readonly getName: (objClass: ObjectClasses, jobType?: JobTypes, isPlural?: boolean) => string;
-    static readonly getIcon: (objClass: ObjectClasses, d: any) => import("react/jsx-runtime").JSX.Element;
-    static readonly getTooltip: (objClass: ObjectClasses, d: any) => import("react/jsx-runtime").JSX.Element | null;
+    static readonly getIcon: (objClass: ObjectClasses, d: any) => React.JSX.Element;
+    static readonly getTooltip: (objClass: ObjectClasses, d: any) => React.JSX.Element | null;
 }