@topconsultnpm/sdkui-react 6.22.0-t1 → 6.22.0-t3

package/lib/services/caseflow/CaseFlowService.js

@@ -0,0 +1,761 @@
+import { SDK_Globals, BlogPost, CaseFlowDcmt, CaseFlowInstanceDescriptor, CaseFlowParticipant, CaseFlowWIOperationDescriptor, MetadataValueDescriptor, CF_ParticipantRoles, CF_States, CF_WIOperations, CF_WorkItemCategories, CF_WorkItemStates, UserListCacheService, DcmtTypeListCacheService, } from '@topconsultnpm/sdk-ts';
+import { CaseFlowTemplateCacheService } from './CaseFlowTemplateCacheService';
+import { getTemplateNameSync, primeTemplateName, primeTemplateNames, primeActionNames } from './caseFlowNameCache';
+export class CaseFlowService {
+    // ----- Template / tipi documento (invariati: cache condivise) ------------
+    /** Elenco dei template reali (via CaseFlowTemplateCacheService). */
+    static async getTemplates() {
+        const templates = await CaseFlowTemplateCacheService.GetAllAsync();
+        // Popola la cache dei nomi template, così i componenti possono risolvere
+        // `templateName` dal `cftid` senza augmentare i descrittori del SDK.
+        primeTemplateNames(templates);
+        return templates;
+    }
+    /**
+     * Singolo template per id. Usa GetAsync (non un find su GetAllAsync): così i
+     * template di cui l'utente NON può creare istanze — ma di cui è destinatario
+     * di un workitem (es. Completamento dati) — vengono risolti on-demand via
+     * RetrieveAsync mirata invece di restituire undefined.
+     */
+    static async getTemplate(id) {
+        const template = await CaseFlowTemplateCacheService.GetAsync(id);
+        if (template)
+            primeTemplateNames([template]);
+        return template;
+    }
+    /** Invalida la cache dei template (dopo creazione/modifica/eliminazione). */
+    static invalidateTemplatesCache() {
+        CaseFlowTemplateCacheService.Invalidate();
+    }
+    /** DcmtTypeDescriptor (copertina) per il TID indicato. */
+    static async getDcmtTypeAsync(tid) {
+        try {
+            return await DcmtTypeListCacheService.GetAsync(tid, true);
+        }
+        catch (e) {
+            console.warn(`[CaseFlow] DcmtType ${tid} non disponibile:`, e);
+            return undefined;
+        }
+    }
+    // ----- Lettura istanze ---------------------------------------------------
+    /** Tutte le istanze visibili all'utente (unione di tutti i template). */
+    static async getCaseflows() {
+        return this.loadAllInstances();
+    }
+    /**
+     * Singola istanza COMPLETA per id. `RetrieveAllAsync` (usata dalla dashboard)
+     * porta i dati necessari alle card, ma per il dettaglio completo
+     * (documenti/bacheca/timeline) serve comunque una `RetrieveAsync(cftid, id)`
+     * che idrata l'istanza. Il `cftid` va passato quando noto (evita una
+     * scansione); in mancanza viene risolto dalla lista.
+     *
+     * ATTENZIONE sui `workItems` della RetrieveAll: contengono i soli workitem
+     * ANCORA APERTI, non lo storico. Una pratica conclusa arriva con
+     * `workItems: []`, perché non ha più nulla di pendente. Chi deve ricostruire
+     * la STORIA di una pratica (chi ha fatto cosa e quando) non può quindi basarsi
+     * sull'elenco: serve la Retrieve completa, e la fonte dei passaggi già
+     * avvenuti sono i messaggi di sistema della bacheca (`blogPosts` con
+     * allegato di riferimento all'azione).
+     */
+    static async getCaseflow(id, cftid) {
+        try {
+            return await this.retrieveCaseflow(id, cftid);
+        }
+        catch (e) {
+            console.warn(`[CaseFlow] RetrieveAsync istanza id=${id} (cftid=${cftid}) fallita:`, e);
+            return undefined;
+        }
+    }
+    /**
+     * Come {@link getCaseflow} ma PROPAGA l'errore invece di inghiottirlo.
+     * Da usare nei punti in cui l'utente apre esplicitamente l'istanza (apertura
+     * scheda, deep link): il fallimento della Retrieve deve essere notificato,
+     * non mascherato da una vista incompleta ("non sei un partecipante").
+     */
+    static async retrieveCaseflow(id, cftid) {
+        const engine = SDK_Globals.tmSession?.NewCaseFlowInstanceEngine();
+        if (!engine)
+            return undefined;
+        let resolvedCftid = cftid;
+        if (resolvedCftid == null) {
+            const all = await this.loadAllInstances();
+            resolvedCftid = all.find(cf => cf.id === id)?.cftid;
+        }
+        if (resolvedCftid == null) {
+            console.warn(`[CaseFlow] impossibile risolvere il cftid per l'istanza id=${id}.`);
+            return undefined;
+        }
+        const full = await engine.RetrieveAsync(resolvedCftid, id);
+        if (!full)
+            return undefined;
+        if (full.cftid == null)
+            full.cftid = resolvedCftid;
+        // Risolvi il template (best-effort, on-demand se non creabile dall'utente)
+        // per l'etichetta del modello e i nomi azione.
+        const tpl = await CaseFlowTemplateCacheService.GetAsync(full.cftid);
+        if (tpl) {
+            primeTemplateName(tpl.id, tpl.name);
+            primeActionNames(tpl);
+        }
+        await this.resolveUserNames([full]);
+        return full;
+    }
+    /** Istanze di cui l'utente indicato è proprietario. */
+    static async getMyCaseflows(userId) {
+        const all = await this.loadAllInstances();
+        return all.filter(cf => cf.ownerID === userId);
+    }
+    /** Ricerca avanzata sulle istanze applicando i filtri indicati. */
+    static async searchCaseflows(criteria) {
+        const all = await this.loadAllInstances();
+        const lowerIncludes = (haystack, needle) => (haystack ?? '').toLowerCase().includes(needle.toLowerCase());
+        return all.filter(cf => {
+            if (criteria.templateId != null && cf.cftid !== criteria.templateId)
+                return false;
+            if (criteria.name && !lowerIncludes(cf.name, criteria.name))
+                return false;
+            if (criteria.description && !lowerIncludes(cf.description, criteria.description))
+                return false;
+            if (criteria.state && cf.state !== criteria.state)
+                return false;
+            if (criteria.dateFrom) {
+                const from = new Date(criteria.dateFrom);
+                if (cf.creationTime && cf.creationTime < from)
+                    return false;
+            }
+            if (criteria.dateTo) {
+                const to = new Date(criteria.dateTo);
+                if (cf.creationTime && cf.creationTime > to)
+                    return false;
+            }
+            if (criteria.metadataFilters && criteria.metadataFilters.length > 0) {
+                for (const mf of criteria.metadataFilters) {
+                    if (!mf.value.trim())
+                        continue;
+                    const cfMeta = (cf.cover ?? []).find(m => m.mid === mf.mid);
+                    if (!cfMeta || !lowerIncludes(cfMeta.value, mf.value))
+                        return false;
+                }
+            }
+            if (criteria.freeTextMetadata && criteria.freeTextMetadata.trim()) {
+                const needle = criteria.freeTextMetadata.trim();
+                const matchesCommon = lowerIncludes(cf.name, needle)
+                    || lowerIncludes(cf.description, needle)
+                    || lowerIncludes(cf.ownerName, needle)
+                    || lowerIncludes(getTemplateNameSync(cf.cftid), needle);
+                const matchesMeta = (cf.cover ?? []).some(m => lowerIncludes(m.value, needle) || lowerIncludes(m.metadataName, needle));
+                if (!matchesCommon && !matchesMeta)
+                    return false;
+            }
+            return true;
+        });
+    }
+    /** WorkItem pendenti assegnati all'utente, raggruppati per istanza. */
+    static async getMyPendingWorkItems(userId) {
+        return this.collectWorkItemsByState(userId, CF_WorkItemStates.Pending);
+    }
+    /**
+     * Richieste di "maggiori informazioni" INVIATE dall'utente e ancora in
+     * attesa di risposta, raggruppate per istanza.
+     *
+     * Non basta filtrare `toUserID === userId && state === MoreInfo` (il solo
+     * workitem "padre" bloccato intestato a me): a seconda di come il backend
+     * materializza la richiesta, l'unico workitem visibile può essere quello
+     * INVIATO al destinatario (`fromUserID === userId`, categoria MoreInfo,
+     * ancora Pending). In quel caso il filtro su `toUserID` non lo intercetta e
+     * l'istanza sparisce da TUTTE le sezioni di "Per te" (non è più Pending per
+     * me, non è MoreInfo intestato a me, e non ne sono owner). Consideriamo
+     * quindi entrambe le rappresentazioni, preferendo il figlio inviato (che
+     * porta il destinatario) ed evitando di mostrare padre + figlio della
+     * stessa richiesta.
+     */
+    static async getMyMoreInfoRequests(userId) {
+        const all = await this.loadAllInstances();
+        const result = [];
+        for (const cf of all) {
+            const wis = cf.workItems ?? [];
+            // Richieste che HO inviato e attendono risposta da un altro utente.
+            const sent = wis.filter(wi => wi.fromUserID === userId
+                && wi.workItemCategory === CF_WorkItemCategories.MoreInfo
+                && wi.state === CF_WorkItemStates.Pending);
+            // Mia attività messa "in attesa" (workitem padre intestato a me).
+            const waitingParents = wis.filter(wi => wi.toUserID === userId && wi.state === CF_WorkItemStates.MoreInfo);
+            const parentsWithoutChild = waitingParents.filter(p => !sent.some(s => s.parentWorkItemID === p.id));
+            const workItems = [...sent, ...parentsWithoutChild];
+            if (workItems.length > 0)
+                result.push({ caseflow: cf, workItems });
+        }
+        return result;
+    }
+    static async collectWorkItemsByState(userId, state) {
+        const all = await this.loadAllInstances();
+        const result = [];
+        for (const cf of all) {
+            const workItems = (cf.workItems ?? []).filter(wi => wi.toUserID === userId && wi.state === state);
+            if (workItems.length > 0)
+                result.push({ caseflow: cf, workItems });
+        }
+        return result;
+    }
+    // ----- Creazione / eliminazione / aggiornamento istanza ------------------
+    /**
+     * Crea una nuova istanza a partire da un template tramite CreateAsync.
+     * I metadati di copertina (metadataValues: mid -> valore) vengono passati
+     * nel campo `cover`. Il backend materializza azioni/stati/partecipanti dal
+     * template identificato da `cftid`.
+     * @returns id della nuova istanza.
+     */
+    static async CreateCaseFlowInstance(template, instanceName, instanceDescription, metadataValues) {
+        const engine = SDK_Globals.tmSession?.NewCaseFlowInstanceEngine();
+        if (!engine)
+            throw new Error('Motore delle istanze CaseFlow non disponibile.');
+        if (template.id == null)
+            throw new Error('Template privo di id (cftid) per la creazione dell\'istanza.');
+        const d = new CaseFlowInstanceDescriptor();
+        d.cftid = template.id;
+        d.name = instanceName;
+        d.description = instanceDescription ?? '';
+        d.state = CF_States.New;
+        d.progress = 0;
+        d.cover = Object.entries(metadataValues).map(([mid, value]) => MetadataValueDescriptor.fromJS({ mid: Number(mid), value }));
+        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.
+     */
+    static async DeleteCaseFlowInstance(instanceId, template) {
+        if (!instanceId)
+            throw new Error('instanceId non valido per la cancellazione.');
+        const engine = SDK_Globals.tmSession?.NewCaseFlowInstanceEngine();
+        if (!engine)
+            throw new Error('Motore delle istanze CaseFlow non disponibile.');
+        const cftid = template?.id ?? (await this.getCaseflow(instanceId))?.cftid;
+        if (cftid == null)
+            throw new Error(`Impossibile risolvere il template (cftid) per l'istanza id=${instanceId}.`);
+        await engine.DeleteAsync(cftid, instanceId);
+        return { instanceDID: instanceId, complete: true, orphaned: [] };
+    }
+    /** Aggiorna un'istanza esistente tramite UpdateAsync. */
+    static async saveCaseflow(caseflow) {
+        const engine = SDK_Globals.tmSession?.NewCaseFlowInstanceEngine();
+        if (!engine)
+            throw new Error('Motore delle istanze CaseFlow non disponibile.');
+        await engine.UpdateAsync(caseflow);
+    }
+    // ----- Bacheca (blog dell'istanza) ---------------------------------------
+    /**
+     * Aggiunge un post in bacheca tramite BlogPostAddAsync(cftid, id, bp). Il
+     * cftid è passato quando noto (evita una Retrieve) oppure risolto dall'istanza.
+     * @returns il post creato (transitorio: la ricarica leggerà quelli reali).
+     */
+    static async addBlogPost(caseFlowId, text, authorId, authorName, attachments, 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}.`);
+        const attachmentsJson = attachments?.map(a => a.toJSON()) ?? [];
+        const bp = BlogPost.fromJS({
+            ownerID: authorId,
+            ownerName: authorName,
+            description: text,
+            isDel: 0,
+            isSys: 0,
+            attachments: attachmentsJson,
+        });
+        const newId = await engine.BlogPostAddAsync(resolvedCftid, caseFlowId, bp);
+        // Post transitorio: rispecchia quanto inviato in attesa della ricarica.
+        return BlogPost.fromJS({
+            id: newId ?? 0,
+            ownerID: authorId,
+            ownerName: authorName,
+            description: text,
+            creationTime: new Date().toISOString(),
+            isDel: 0,
+            isSys: 0,
+            attachments: attachmentsJson,
+        });
+    }
+    /**
+     * Elimina (o ripristina) un post in bacheca tramite
+     * BlogPostDeleteOrUndeleteAsync(cftid, id, postID, del).
+     */
+    static async deleteOrUndeleteBlogPost(caseFlowId, postId, del, 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.BlogPostDeleteOrUndeleteAsync(resolvedCftid, caseFlowId, postId, del);
+    }
+    // ----- Documenti della pratica --------------------------------------------
+    //
+    // Come per i partecipanti, l'engine espone UNA sola API,
+    // DcmtAddOrRemoveAsync(cftid, id, tid, did, remove): con remove=false aggancia
+    // il documento all'istanza, con remove=true lo sgancia.
+    /**
+     * Aggancia un documento (nuovo archiviato o già presente in archivio)
+     * all'istanza tramite DcmtAddOrRemoveAsync(remove=false).
+     * @returns descrittore transitorio del documento agganciato (la ricarica
+     *          dell'istanza leggerà quello reale).
+     */
+    static async addDcmtToInstance(caseFlowId, tid, did, cftid) {
+        await this.dcmtAddOrRemove(caseFlowId, tid, did, false, cftid);
+        return CaseFlowDcmt.fromJS({ tid, did, creationTime: new Date().toISOString() });
+    }
+    /** Sgancia un documento dall'istanza tramite DcmtAddOrRemoveAsync(remove=true). */
+    static async removeDcmtFromInstance(caseFlowId, tid, did, cftid) {
+        await this.dcmtAddOrRemove(caseFlowId, tid, did, true, cftid);
+    }
+    // ----- Regole documenti attesi dell'istanza (dcmtRules) -------------------
+    //
+    // Finché l'istanza non ha regole proprie (dcmtRules assente o vuota) i
+    // documenti attesi — con min e max — sono i dcmts del template. Un
+    // supervisor può personalizzarle per la SOLA istanza tramite l'unica API
+    // DcmtRuleAddOrRemoveAsync(cftid, id, tid, min, max, remove): con
+    // remove=false funge da UPSERT della regola per il TID, con remove=true la
+    // rimuove. Rimuovendo tutte le regole l'istanza torna a seguire il template.
+    /** Aggiunge o aggiorna (upsert) la regola documenti del TID sulla sola istanza. */
+    static async saveDcmtRule(caseFlowId, tid, min, max, cftid) {
+        await this.dcmtRuleAddOrRemove(caseFlowId, tid, min, max, false, cftid);
+    }
+    /** Rimuove la regola documenti del TID dalla sola istanza. */
+    static async removeDcmtRule(caseFlowId, tid, cftid) {
+        await this.dcmtRuleAddOrRemove(caseFlowId, tid, 0, 0, true, cftid);
+    }
+    /**
+     * Chiama DcmtRuleAddOrRemoveAsync(cftid, id, tid, min, max, remove)
+     * risolvendo il cftid quando non passato (come per bacheca e partecipanti).
+     */
+    static async dcmtRuleAddOrRemove(caseFlowId, tid, min, max, remove, 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.DcmtRuleAddOrRemoveAsync(resolvedCftid, caseFlowId, tid, min, max, remove);
+    }
+    /**
+     * Chiama DcmtAddOrRemoveAsync(cftid, id, tid, did, remove) risolvendo il
+     * cftid quando non passato (come per bacheca e partecipanti).
+     */
+    static async dcmtAddOrRemove(caseFlowId, tid, did, remove, 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.DcmtAddOrRemoveAsync(resolvedCftid, caseFlowId, tid, did, remove);
+    }
+    /**
+     * Allega un file alla pratica tramite AttachAddAsync(cftid, id, ...).
+     * @returns il DID dell'allegato appena archiviato.
+     */
+    static async addAttachment(caseFlowId, file, name, description, 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}.`);
+        return await engine.AttachAddAsync(resolvedCftid, caseFlowId, name, description, file);
+    }
+    /**
+     * Toglie l'allegato dalla pratica tramite AttachRemoveAsync(cftid, id, attachDID).
+     * A differenza dello sgancio di un documento d'archivio, qui il file viene
+     * anche cancellato: un allegato fuori dalla sua pratica non ha più senso.
+     */
+    static async removeAttachment(caseFlowId, attachDID, 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.AttachRemoveAsync(resolvedCftid, caseFlowId, attachDID);
+    }
+    // ----- Partecipanti ------------------------------------------------------
+    //
+    // Per scelta del backend l'engine espone UNA sola API,
+    // ParticipantsAddOrRemoveAsync(cftid, id, d, remove): con remove=false funge
+    // da UPSERT (aggiunge il partecipante oppure ne aggiorna ruolo/permessi Guest
+    // se già presente), con remove=true lo rimuove. Non esiste — né esisterà — un
+    // metodo di Update dedicato: modifica ruolo e permessi passano dallo stesso
+    // upsert. Il partecipante identifica l'utente col campo `id` (ex `userId`).
+    /**
+     * Aggiunge un partecipante all'istanza (o ne aggiorna ruolo/permessi se già
+     * presente) tramite ParticipantsAddOrRemoveAsync(remove=false).
+     */
+    static async addParticipant(caseFlowId, userId, userName, role, guestPermissions, cftid) {
+        const participant = CaseFlowParticipant.fromJS({
+            id: userId,
+            name: userName,
+            role,
+            guestPermissions: guestPermissions?.toJSON(),
+        });
+        await this.participantsAddOrRemove(caseFlowId, participant, false, cftid);
+        return participant;
+    }
+    /** Rimuove un partecipante dall'istanza tramite ParticipantsAddOrRemoveAsync(remove=true). */
+    static async removeParticipant(caseFlowId, userId, cftid) {
+        const participant = CaseFlowParticipant.fromJS({ id: userId });
+        await this.participantsAddOrRemove(caseFlowId, participant, true, cftid);
+    }
+    /**
+     * Cambia il ruolo di un partecipante ri-applicando l'upsert col nuovo ruolo
+     * (non esiste un'Update dedicata). Passando a Guest si conservano/impostano i
+     * relativi permessi.
+     */
+    static async changeParticipantRole(caseFlowId, userId, role, guestPermissions, cftid) {
+        const participant = CaseFlowParticipant.fromJS({
+            id: userId,
+            role,
+            guestPermissions: role === CF_ParticipantRoles.Guest ? guestPermissions?.toJSON() : undefined,
+        });
+        await this.participantsAddOrRemove(caseFlowId, participant, false, cftid);
+    }
+    /** Aggiorna i permessi Guest di un partecipante (upsert col ruolo Guest). */
+    static async updateParticipantGuestPermissions(caseFlowId, userId, permissions, cftid) {
+        const participant = CaseFlowParticipant.fromJS({
+            id: userId,
+            role: CF_ParticipantRoles.Guest,
+            guestPermissions: permissions.toJSON(),
+        });
+        await this.participantsAddOrRemove(caseFlowId, participant, false, cftid);
+    }
+    /**
+     * Chiama ParticipantsAddOrRemoveAsync(cftid, id, d, remove) risolvendo il
+     * cftid quando non passato (come per la bacheca).
+     */
+    static async participantsAddOrRemove(caseFlowId, participant, remove, 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.ParticipantsAddOrRemoveAsync(resolvedCftid, caseFlowId, participant, remove);
+    }
+    // ----- Azioni personali dell'utente (Preferiti / Segui) -------------------
+    //
+    // Riguardano la relazione fra UTENTE e istanza, non il ciclo di vita della
+    // pratica. Come per documenti e partecipanti, l'engine espone un'unica API
+    // add-or-remove per ciascuna delle due.
+    //
+    // ATTENZIONE all'asimmetria: dei Preferiti si può leggere l'elenco
+    // (FavoritesRetrieveAllAsync), del Segui NO. Nessuna API dice se l'utente
+    // corrente segue una pratica: le `FollowAddOrRemove` sono di sola scrittura,
+    // qui come per pratiche-dossier e gruppi di lavoro. Finché il backend non
+    // esporrà `IsFollow` sul descrittore d'istanza, lo stato del comando Segui
+    // resta a carico del chiamante.
+    /** Istanze marcate come preferite dall'utente corrente. */
+    static async getFavorites() {
+        const engine = SDK_Globals.tmSession?.NewCaseFlowInstanceEngine();
+        if (!engine)
+            throw new Error('Motore delle istanze CaseFlow non disponibile.');
+        return await engine.FavoritesRetrieveAllAsync() ?? [];
+    }
+    /**
+     * Aggiunge o rimuove l'istanza dai preferiti dell'utente corrente tramite
+     * FavoritesAddOrRemoveAsync(cftid, id, remove).
+     */
+    static async setFavorite(caseFlowId, favorite, 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.FavoritesAddOrRemoveAsync(resolvedCftid, caseFlowId, !favorite);
+    }
+    /**
+     * Inizia o smette di seguire l'istanza tramite
+     * FollowAddOrRemoveAsync(cftid, id, remove).
+     */
+    static async setFollow(caseFlowId, follow, 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.FollowAddOrRemoveAsync(resolvedCftid, caseFlowId, !follow);
+    }
+    /**
+     * Stato "l'utente corrente segue questa pratica" letto dal descrittore.
+     *
+     * `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`
+     * righe e il solo ultimo post non di sistema per oggetto, quindi chi segue
+     * un oggetto senza post risulta "non seguace"; per le istanze di CaseFlow,
+     * poi, non esiste nemmeno un ramo nella UNION.
+     */
+    static readFollowFlag(cf) {
+        return cf.isFollow;
+    }
+    // ----- Workitem: movimentazione del flusso -------------------------------
+    //
+    // L'engine espone UNA sola API per la movimentazione dei workitem,
+    // ExecuteWorkItemOperationAsync(cftid, id, operation): il tipo di operazione
+    // (Complete, Reject, RequestMoreInfo, RespondMoreInfo, Assign, ForceComplete,
+    // ForceReject, ...) è indicato in `operation.operation` e i soli dati pertinenti
+    // (wiid, actionID, toUserID, comment, metadataValues) vengono valorizzati in
+    // base all'operazione. I messaggi in bacheca (nota di completamento, motivo del
+    // rifiuto, richiesta informazioni) sono inseriti DIRETTAMENTE dal backend a
+    // partire dal `comment`: la UI non deve più creare post di bacheca a mano.
+    /** Completa (approva) un workitem. La nota facoltativa viene pubblicata in bacheca dal backend. */
+    static async completeWorkItem(caseFlowId, workItemId, response, cftid) {
+        await this.executeWorkItemOperation(caseFlowId, CaseFlowWIOperationDescriptor.fromJS({
+            operation: CF_WIOperations.Complete,
+            wiid: workItemId,
+            comment: response,
+        }), cftid);
+    }
+    /**
+     * Completa un workitem di "Completamento dati": i metadati valorizzati
+     * (mid -> valore) viaggiano in `metadataValues`; il backend li applica al
+     * documento master dell'istanza e completa il workitem.
+     */
+    static async completeDataCompletionWorkItem(caseFlowId, workItemId, metadataValues, response, cftid) {
+        await this.executeWorkItemOperation(caseFlowId, CaseFlowWIOperationDescriptor.fromJS({
+            operation: CF_WIOperations.Complete,
+            wiid: workItemId,
+            comment: response,
+            metadataValues: Object.entries(metadataValues).map(([mid, value]) => ({ mid: Number(mid), value })),
+        }), cftid);
+    }
+    /** Rifiuta un workitem. Il motivo viene pubblicato in bacheca dal backend. */
+    static async rejectWorkItem(caseFlowId, workItemId, response, cftid) {
+        await this.executeWorkItemOperation(caseFlowId, CaseFlowWIOperationDescriptor.fromJS({
+            operation: CF_WIOperations.Reject,
+            wiid: workItemId,
+            comment: response,
+        }), cftid);
+    }
+    /**
+     * 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,
+            actionID,
+            toUserID,
+            comment: description,
+        }), cftid);
+    }
+    /** Forza il completamento di un'azione (supervisor). */
+    static async forceCompleteAction(caseFlowId, actionID, reason, cftid) {
+        await this.executeWorkItemOperation(caseFlowId, CaseFlowWIOperationDescriptor.fromJS({
+            operation: CF_WIOperations.ForceComplete,
+            actionID,
+            comment: reason,
+        }), cftid);
+    }
+    /** Forza il rifiuto di un'azione (supervisor). Il motivo è obbligatorio. */
+    static async forceRejectAction(caseFlowId, actionID, reason, cftid) {
+        await this.executeWorkItemOperation(caseFlowId, CaseFlowWIOperationDescriptor.fromJS({
+            operation: CF_WIOperations.ForceReject,
+            actionID,
+            comment: reason,
+        }), cftid);
+    }
+    /**
+     * Richiede maggiori informazioni a un altro utente: il backend crea il
+     * workitem MoreInfo figlio assegnato a `targetUserId` e registra la richiesta.
+     */
+    static async requestMoreInfo(caseFlowId, workItemId, targetUserId, message, cftid) {
+        await this.executeWorkItemOperation(caseFlowId, CaseFlowWIOperationDescriptor.fromJS({
+            operation: CF_WIOperations.RequestMoreInfo,
+            wiid: workItemId,
+            toUserID: targetUserId,
+            comment: message,
+        }), cftid);
+    }
+    /** Risponde a una richiesta di informazioni completando il workitem MoreInfo. */
+    static async respondToMoreInfo(caseFlowId, moreInfoWorkItemId, response, cftid) {
+        await this.executeWorkItemOperation(caseFlowId, CaseFlowWIOperationDescriptor.fromJS({
+            operation: CF_WIOperations.RespondMoreInfo,
+            wiid: moreInfoWorkItemId,
+            comment: response,
+        }), cftid);
+    }
+    /**
+     * Chiama ExecuteWorkItemOperationAsync(cftid, id, operation) risolvendo il
+     * cftid quando non passato (come per bacheca, documenti e partecipanti).
+     */
+    static async executeWorkItemOperation(caseFlowId, operation, 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.ExecuteWorkItemOperationAsync(resolvedCftid, caseFlowId, operation);
+    }
+    static loadAllInstances() {
+        if (this._inFlightInstances)
+            return this._inFlightInstances;
+        const p = this.doLoadAllInstances().finally(() => {
+            if (this._inFlightInstances === p)
+                this._inFlightInstances = undefined;
+        });
+        this._inFlightInstances = p;
+        return p;
+    }
+    static async doLoadAllInstances() {
+        const engine = SDK_Globals.tmSession?.NewCaseFlowInstanceEngine();
+        if (!engine)
+            return [];
+        // cftid=0 => TUTTE le istanze visibili all'utente in un'unica chiamata,
+        // cross-template (owner, partecipante di template o di singola istanza),
+        // incluse quelle di template NON visibili all'utente.
+        //
+        // TRANSIZIONE: finché il backend non supporta `cftid=0`, la chiamata può
+        // fallire o tornare vuota. In quel caso si ripiega sull'enumerazione
+        // per-template (copre gli utenti che vedono i template). Rimuovere il
+        // fallback quando `cftid=0` sarà stabile lato backend.
+        let list = [];
+        try {
+            list = (await engine.RetrieveAllAsync(0)) ?? [];
+        }
+        catch (e) {
+            console.warn('[CaseFlow] RetrieveAll(0) non disponibile, ripiego per-template:', e);
+        }
+        if (list.length === 0) {
+            list = await this.loadInstancesPerTemplate(engine);
+        }
+        const instances = [];
+        const seen = new Set();
+        for (const inst of list) {
+            // Salvaguardia anti-duplicati per id.
+            if (inst.id != null) {
+                if (seen.has(inst.id))
+                    continue;
+                seen.add(inst.id);
+            }
+            instances.push(inst);
+        }
+        // Risolvi i template di TUTTI i cftid presenti per popolare le cache di
+        // nome template e nome azione (usate in rendering). GetAsync risolve
+        // on-demand anche i template non creabili dall'utente (di cui però
+        // partecipa a un'istanza), che altrimenti la cache non conoscerebbe.
+        // Best-effort: se un template non è risolvibile, l'etichetta degrada su
+        // `Modello #<cftid>` senza nascondere l'istanza.
+        const cftids = [...new Set(instances.map(i => i.cftid).filter((c) => c != null))];
+        await Promise.all(cftids.map(async (cftid) => {
+            const tpl = await CaseFlowTemplateCacheService.GetAsync(cftid);
+            if (tpl) {
+                primeTemplateName(tpl.id, tpl.name);
+                primeActionNames(tpl);
+            }
+        }));
+        await this.resolveUserNames(instances);
+        return instances;
+    }
+    /**
+     * Fallback di TRANSIZIONE: enumera le istanze template per template usando
+     * l'elenco dei template visibili all'utente. Non copre le istanze di template
+     * NON visibili (partecipante a livello di istanza): per quelle serve la
+     * RetrieveAll cross-template (cftid=0). Da rimuovere quando cftid=0 è stabile.
+     */
+    static async loadInstancesPerTemplate(engine) {
+        const templates = await this.getTemplates();
+        const collected = [];
+        await Promise.all(templates.map(async (t) => {
+            if (t.id == null)
+                return;
+            try {
+                const l = await engine.RetrieveAllAsync(t.id);
+                for (const inst of l ?? []) {
+                    if (inst.cftid == null)
+                        inst.cftid = t.id;
+                    collected.push(inst);
+                }
+            }
+            catch (e) {
+                console.warn(`[CaseFlow] RetrieveAll istanze per template ${t.id} fallito:`, e);
+            }
+        }));
+        return collected;
+    }
+    /** Valorizza `ownerName` sulle istanze (best-effort, via cache utenti). */
+    static async resolveUserNames(instances) {
+        const ids = new Set();
+        for (const inst of instances) {
+            if (inst.ownerID != null)
+                ids.add(inst.ownerID);
+        }
+        const nameById = new Map();
+        await Promise.all([...ids].map(async (id) => {
+            try {
+                const u = await UserListCacheService.GetAsync(id);
+                nameById.set(id, u?.name ?? `Utente ${id}`);
+            }
+            catch {
+                nameById.set(id, `Utente ${id}`);
+            }
+        }));
+        for (const inst of instances) {
+            if (inst.ownerID != null && !inst.ownerName)
+                inst.ownerName = nameById.get(inst.ownerID);
+        }
+    }
+}