@topconsultnpm/sdkui-react 6.22.0-dev2.2 → 6.22.0-dev2.21

package/lib/hooks/useTMDistinctValuesSource.js

@@ -0,0 +1,105 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { DataColumnTypes, DcmtTypeListCacheService, MetadataDataTypes, SDK_Globals } from '@topconsultnpm/sdk-ts';
+import { TMExceptionBoxManager } from '../components/base/TMPopUp';
+import TMSpinner from '../components/base/TMSpinner';
+import { customizeSearchByDisplayText, getDateDisplayText } from '../helper';
+import { getDateDisplayFormat, withRowIndex } from './tmDistinctValuesGridHelper';
+import { needsDisplayValue } from './useTMDistinctValuesMetadataDisplay';
+/** Nel risultato dei valori distinti la prima colonna è il valore, la seconda il numero di documenti che lo contengono */
+const COUNT_COL_INDEX = 1;
+/** Numero massimo di valori distinti richiesti al server: il conteggio dice quanti ne sono arrivati sul totale */
+const MAX_DISTINCT_VALUES = 10000;
+/**
+ * Sorgente "valori distinti" di TMDistinctValues: carica i valori del metadato con il relativo numero di
+ * documenti e ne espone righe, colonne e conteggi già pronti per la griglia.
+ *
+ * È anche la sorgente da cui viene il descrittore del metadato (`md`), usato dal pannello per permessi,
+ * titolo e visibilità dell'accodamento: per questo viene caricata anche quando è attiva la ricerca rapida.
+ */
+export const useTMDistinctValuesSource = ({ tid, mid, display }) => {
+    const { loadDisplayCachesAsync, displayValueColumnProps, getMetadataDisplayValue } = display;
+    const [md, setMd] = useState();
+    const [dataSource, setDataSource] = useState([]);
+    const [counts, setCounts] = useState();
+    // Identifica la richiesta corrente: dopo ogni await le risposte delle richieste obsolete vengono scartate
+    const requestIdRef = useRef(0);
+    // Cambiando campo i valori distinti vanno ricaricati: sono la sorgente su cui si torna cambiando
+    // modalità e quella da cui viene il metadato del campo
+    useEffect(() => { loadAsync(); }, [tid, mid]);
+    const loadAsync = async () => {
+        if (!tid)
+            return;
+        const requestId = ++requestIdRef.current;
+        const isStale = () => requestId !== requestIdRef.current;
+        // Svuota subito la griglia: evita di mostrare i valori del tid/mid precedente durante il caricamento
+        setDataSource([]);
+        setCounts(undefined);
+        try {
+            TMSpinner.show({ description: 'Caricamento dei valori distinti...' });
+            const dtd = await DcmtTypeListCacheService.GetAsync(tid, true);
+            const currentMd = dtd?.metadata?.find(o => o.id === mid);
+            const result = await SDK_Globals.tmSession?.NewSearchEngine().GetDistinctValuesAsync(tid, mid, MAX_DISTINCT_VALUES);
+            if (isStale())
+                return;
+            // La prima colonna del risultato è quella dei valori distinti
+            await loadDisplayCachesAsync([currentMd], result?.dtdResult?.rows);
+            if (isStale())
+                return;
+            setMd(currentMd);
+            setDataSource(convertDataTableToObject(result?.dtdResult));
+            setCounts({ returned: result?.dcmtsReturned ?? 0, found: result?.dcmtsFound ?? 0 });
+        }
+        catch (e) {
+            if (isStale())
+                return;
+            TMExceptionBoxManager.show({ exception: e });
+        }
+        finally {
+            TMSpinner.hide();
+        }
+    };
+    const columns = useMemo(() => {
+        const isDateColumn = md?.dataType === MetadataDataTypes.DateTime;
+        return ([
+            {
+                dataField: 'value', dataType: isDateColumn ? 'date' : 'string', caption: md?.nameLoc,
+                ...(isDateColumn && { format: getDateDisplayFormat(md?.format?.format, md?.format?.formatCulture) }),
+                ...displayValueColumnProps(md, 'value')
+            },
+            { dataField: 'Count', dataType: 'number', caption: 'N°' }
+        ]);
+    }, [md, displayValueColumnProps]);
+    // La colonna del valore mostra la data formattata o la descrizione: la ricerca va fatta su quel testo
+    const searchTextGetters = useMemo(() => {
+        const getters = new Map();
+        if (md?.dataType === MetadataDataTypes.DateTime) {
+            getters.set('value', (rowData) => getDateDisplayText(rowData?.value, md?.format?.format, md?.format?.formatCulture));
+        }
+        else if (needsDisplayValue(md)) {
+            getters.set('value', (rowData) => String(getMetadataDisplayValue(md, rowData?.value) ?? ''));
+        }
+        return getters;
+    }, [md, getMetadataDisplayValue]);
+    const customizeColumns = useMemo(() => customizeSearchByDisplayText(searchTextGetters), [searchTextGetters]);
+    return { md, dataSource, counts, columns, customizeColumns, loadAsync };
+};
+const convertDataTableToObject = (dtdResult) => {
+    if (!dtdResult?.columns?.length || !dtdResult?.rows?.length)
+        return [];
+    // Descrittori di colonna calcolati una sola volta invece che per ogni riga
+    const columns = [];
+    dtdResult.columns.forEach((col, colIndex) => {
+        if (col?.caption) {
+            columns.push({ index: colIndex, key: colIndex === 0 ? "value" : col.caption, isNumber: col.dataType === DataColumnTypes.Number });
+        }
+    });
+    // I valori più frequenti in testa: il conteggio è nella seconda colonna del risultato
+    const sortedRows = dtdResult.rows.slice().sort((a, b) => (Number(b?.[COUNT_COL_INDEX]) || 0) - (Number(a?.[COUNT_COL_INDEX]) || 0));
+    return withRowIndex(sortedRows.map((row) => {
+        const rowObject = {};
+        columns.forEach((col) => {
+            rowObject[col.key] = col.isNumber ? row?.[col.index]?.replace('.', ',') : row?.[col.index] ?? null;
+        });
+        return rowObject;
+    }));
+};

package/lib/index.d.ts

@@ -8,6 +8,7 @@ export * from './hooks/useQueryParametersDialog';
 export * from './hooks/useDcmtOperations';
 export * from './hooks/useResizeObserver';
 export * from './hooks/useWorkflowApprove';
+export * from './hooks/useCaseFlowApprove';
 export * from './hooks/useRelatedDocuments';
 export * from './hooks/useSettingsFeedback';
 export * from './hooks/useBetaFeatures';

package/lib/index.js

@@ -8,6 +8,7 @@ export * from './hooks/useQueryParametersDialog';
 export * from './hooks/useDcmtOperations';
 export * from './hooks/useResizeObserver';
 export * from './hooks/useWorkflowApprove';
+export * from './hooks/useCaseFlowApprove';
 export * from './hooks/useRelatedDocuments';
 export * from './hooks/useSettingsFeedback';
 export * from './hooks/useBetaFeatures';

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

@@ -0,0 +1,236 @@
+import { BlogPost, BlogPostAttachment, CaseFlowDcmt, CaseFlowGuestPermissions, CaseFlowInstanceDescriptor, CaseFlowParticipant, CaseFlowTemplateDescriptor, CaseFlowWorkItem, DcmtTypeDescriptor, CF_ParticipantRoles, CF_States } from '@topconsultnpm/sdk-ts';
+type PendingGroup = Array<{
+    caseflow: CaseFlowInstanceDescriptor;
+    workItems: CaseFlowWorkItem[];
+}>;
+/** Criteri di ricerca delle istanze (pannello Ricerca e Process Mining). */
+export interface CaseFlowSearchCriteria {
+    templateId?: number;
+    name?: string;
+    description?: string;
+    state?: CF_States;
+    dateFrom?: string;
+    dateTo?: string;
+    metadataFilters?: Array<{
+        mid: number;
+        value: string;
+    }>;
+    /** Ricerca libera: cerca il valore in tutti i metadati di qualsiasi template */
+    freeTextMetadata?: string;
+}
+/** Documento non cancellato durante l'eliminazione di un'istanza (orfano). */
+export interface CaseFlowDeleteOrphan {
+    tid: number;
+    did: number;
+    /** Motivo del fallimento (tipicamente "Document not accessible by this user"). */
+    reason: string;
+}
+/** Esito dell'eliminazione di un'istanza di CaseFlow. */
+export interface CaseFlowDeleteResult {
+    instanceDID: number;
+    /** true se tutti i documenti individuati sono stati cancellati. */
+    complete: boolean;
+    /** Documenti non cancellati perché non accessibili all'utente (vista parametrica/CdV). */
+    orphaned: CaseFlowDeleteOrphan[];
+}
+export declare class CaseFlowService {
+    /** Elenco dei template reali (via CaseFlowTemplateCacheService). */
+    static getTemplates(): Promise<CaseFlowTemplateDescriptor[]>;
+    /**
+     * 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 getTemplate(id: number): Promise<CaseFlowTemplateDescriptor | undefined>;
+    /** Invalida la cache dei template (dopo creazione/modifica/eliminazione). */
+    static invalidateTemplatesCache(): void;
+    /** DcmtTypeDescriptor (copertina) per il TID indicato. */
+    static getDcmtTypeAsync(tid: number): Promise<DcmtTypeDescriptor | undefined>;
+    /** Tutte le istanze visibili all'utente (unione di tutti i template). */
+    static getCaseflows(): Promise<CaseFlowInstanceDescriptor[]>;
+    /**
+     * 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 getCaseflow(id: number, cftid?: number): Promise<CaseFlowInstanceDescriptor | 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 retrieveCaseflow(id: number, cftid?: number): Promise<CaseFlowInstanceDescriptor | undefined>;
+    /** Istanze di cui l'utente indicato è proprietario. */
+    static getMyCaseflows(userId: number): Promise<CaseFlowInstanceDescriptor[]>;
+    /** Ricerca avanzata sulle istanze applicando i filtri indicati. */
+    static searchCaseflows(criteria: CaseFlowSearchCriteria): Promise<CaseFlowInstanceDescriptor[]>;
+    /** WorkItem pendenti assegnati all'utente, raggruppati per istanza. */
+    static getMyPendingWorkItems(userId: number): Promise<PendingGroup>;
+    /**
+     * 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 getMyMoreInfoRequests(userId: number): Promise<PendingGroup>;
+    private static collectWorkItemsByState;
+    /**
+     * 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 CreateCaseFlowInstance(template: CaseFlowTemplateDescriptor, instanceName: string, instanceDescription: string | undefined, metadataValues: Record<number, string>): Promise<number>;
+    /**
+     * Elimina un'istanza tramite DeleteAsync(cftid, id). Il cftid è preso dal
+     * template fornito (se disponibile) oppure risolto dall'istanza.
+     */
+    static DeleteCaseFlowInstance(instanceId: number, template?: CaseFlowTemplateDescriptor): Promise<CaseFlowDeleteResult>;
+    /** Aggiorna un'istanza esistente tramite UpdateAsync. */
+    static saveCaseflow(caseflow: CaseFlowInstanceDescriptor): Promise<void>;
+    /**
+     * 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 addBlogPost(caseFlowId: number, text: string, authorId: number, authorName: string, attachments?: BlogPostAttachment[], cftid?: number): Promise<BlogPost>;
+    /**
+     * Elimina (o ripristina) un post in bacheca tramite
+     * BlogPostDeleteOrUndeleteAsync(cftid, id, postID, del).
+     */
+    static deleteOrUndeleteBlogPost(caseFlowId: number, postId: number, del: boolean, cftid?: number): Promise<void>;
+    /**
+     * 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 addDcmtToInstance(caseFlowId: number, tid: number, did: number, cftid?: number): Promise<CaseFlowDcmt | undefined>;
+    /** Sgancia un documento dall'istanza tramite DcmtAddOrRemoveAsync(remove=true). */
+    static removeDcmtFromInstance(caseFlowId: number, tid: number, did: number, cftid?: number): Promise<void>;
+    /** Aggiunge o aggiorna (upsert) la regola documenti del TID sulla sola istanza. */
+    static saveDcmtRule(caseFlowId: number, tid: number, min: number, max: number, cftid?: number): Promise<void>;
+    /** Rimuove la regola documenti del TID dalla sola istanza. */
+    static removeDcmtRule(caseFlowId: number, tid: number, cftid?: number): Promise<void>;
+    /**
+     * Chiama DcmtRuleAddOrRemoveAsync(cftid, id, tid, min, max, remove)
+     * risolvendo il cftid quando non passato (come per bacheca e partecipanti).
+     */
+    private static dcmtRuleAddOrRemove;
+    /**
+     * Chiama DcmtAddOrRemoveAsync(cftid, id, tid, did, remove) risolvendo il
+     * cftid quando non passato (come per bacheca e partecipanti).
+     */
+    private static dcmtAddOrRemove;
+    /**
+     * Aggiunge un partecipante all'istanza (o ne aggiorna ruolo/permessi se già
+     * presente) tramite ParticipantsAddOrRemoveAsync(remove=false).
+     */
+    static addParticipant(caseFlowId: number, userId: number, userName: string, role: CF_ParticipantRoles, guestPermissions?: CaseFlowGuestPermissions, cftid?: number): Promise<CaseFlowParticipant | undefined>;
+    /** Rimuove un partecipante dall'istanza tramite ParticipantsAddOrRemoveAsync(remove=true). */
+    static removeParticipant(caseFlowId: number, userId: number, cftid?: number): Promise<void>;
+    /**
+     * 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 changeParticipantRole(caseFlowId: number, userId: number, role: CF_ParticipantRoles, guestPermissions?: CaseFlowGuestPermissions, cftid?: number): Promise<void>;
+    /** Aggiorna i permessi Guest di un partecipante (upsert col ruolo Guest). */
+    static updateParticipantGuestPermissions(caseFlowId: number, userId: number, permissions: CaseFlowGuestPermissions, cftid?: number): Promise<void>;
+    /**
+     * Chiama ParticipantsAddOrRemoveAsync(cftid, id, d, remove) risolvendo il
+     * cftid quando non passato (come per la bacheca).
+     */
+    private static participantsAddOrRemove;
+    /** Istanze marcate come preferite dall'utente corrente. */
+    static getFavorites(): Promise<CaseFlowInstanceDescriptor[]>;
+    /**
+     * Aggiunge o rimuove l'istanza dai preferiti dell'utente corrente tramite
+     * FavoritesAddOrRemoveAsync(cftid, id, remove).
+     */
+    static setFavorite(caseFlowId: number, favorite: boolean, cftid?: number): Promise<void>;
+    /**
+     * Inizia o smette di seguire l'istanza tramite
+     * FollowAddOrRemoveAsync(cftid, id, remove).
+     */
+    static setFollow(caseFlowId: number, follow: boolean, cftid?: number): Promise<void>;
+    /**
+     * 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.
+     *
+     * 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: CaseFlowInstanceDescriptor): boolean | undefined;
+    /** Completa (approva) un workitem. La nota facoltativa viene pubblicata in bacheca dal backend. */
+    static completeWorkItem(caseFlowId: number, workItemId: number, response?: string, cftid?: number): Promise<void>;
+    /**
+     * 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 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). */
+    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>;
+    /** Forza il rifiuto di un'azione (supervisor). Il motivo è obbligatorio. */
+    static forceRejectAction(caseFlowId: number, actionID: number, reason: string, cftid?: number): Promise<void>;
+    /**
+     * Richiede maggiori informazioni a un altro utente: il backend crea il
+     * workitem MoreInfo figlio assegnato a `targetUserId` e registra la richiesta.
+     */
+    static requestMoreInfo(caseFlowId: number, workItemId: number, targetUserId: number, message?: string, cftid?: number): Promise<void>;
+    /** Risponde a una richiesta di informazioni completando il workitem MoreInfo. */
+    static respondToMoreInfo(caseFlowId: number, moreInfoWorkItemId: number, response: string, cftid?: number): Promise<void>;
+    /**
+     * Chiama ExecuteWorkItemOperationAsync(cftid, id, operation) risolvendo il
+     * cftid quando non passato (come per bacheca, documenti e partecipanti).
+     */
+    private static executeWorkItemOperation;
+    private static _inFlightInstances?;
+    private static loadAllInstances;
+    private static doLoadAllInstances;
+    /**
+     * 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.
+     */
+    private static loadInstancesPerTemplate;
+    /** Valorizza `ownerName` sulle istanze (best-effort, via cache utenti). */
+    private static resolveUserNames;
+}
+export {};