Table of Contents

FLOW-DOC-001 — Creazione di un documento (core documentale) — DocCenter

Flusso end-to-end di creazione di un documento nell'entità core del documentale (Document / DocCenter). Path pilota: wizard interattivo DocumentCreateControl.ascx (operatore che crea un nuovo documento con allegato principale, tag e attributi custom). Backend Oracle INFOCAD_TEST38, accesso via stored procedure ODP.NET (nessun ORM). L'entità è persistita nella tabella DOCS_DOCUMENT.

Distinto da FLOW-ECM-001: qui si documenta la scrittura sull'entità documento core (tabelle DOCS_* dell'hub INFOCAD_TEST38), NON il salvataggio su repository ECM esterno (Alfresco/OpenText/Docs), che è un percorso separato (Customizations/ExternalDocSave.*).

  • Flow ID: FLOW-DOC-001
  • Repository: InfocadWeb (ASP.NET Web Forms, VB.NET, DocCenterWeb) + InfocadServer (DocumentControllers → DocumentBL → DocumentDAL, VB.NET)
  • has_standalone_write: true — esiste un path di scrittura autonomo e pulito sull'entità core (DOCS_DOCUMENT), tramite DocumentController.Insert → DOC_CREATEDOCUMENT.
  • Confidence complessiva: VERIFIED (catena UI → code-behind → controller → BL → DAL → stored procedure, confermata su codice E su sorgente DB user_source) · SUPPORTED (wiring controller→BL via .NET Remoting DAOFactory).

Obiettivo di business

Consentire a un operatore del DocCenter di creare un nuovo documento (anagrafica + allegato principale + tag di classificazione + attributi custom) all'interno dell'archivio documentale. Al termine il documento esiste nella tabella DOCS_DOCUMENT con: id generato, protocollo di sistema assegnato, eventuale allegato binario su DOCS_ATTACHMENT, associazioni tag su DOCS_TAG_DOCUMENT e attributi custom su DOCS_DOCUMENT_ATTRIBUTE.

Attori

  • Operatore DocCenter (utente autenticato) — path interattivo wizard DocumentCreateControl.ascx (bottoni Salva / Salva e pubblica).
  • Sistemi esterni / processi massivi — controlli custom di upload (UploadProcessControl.ascx, DocumentInsertControl.ascx) che chiamano lo stesso DocumentController.Insert.
  • Oracle INFOCAD_TEST38 (hub documentale; stored procedure DOC_CREATEDOCUMENT e sotto-procedure).

Trigger

Click sul pulsante Salva (btnSalva) del wizard di creazione documento: evento btnSalva_Click in DocumentCreateControl.ascx.vb:1243, che dopo Me.Validate invoca CreateDocument() (:1246). Variante Salva e pubblica: btnSalvaPubblica_Click (:1257) → CreateDocument(True) (:1259, con auto-pubblicazione workflow).

Frontend entry point

  • Control wizard: DocCenterWeb/UserControls/Custom/DocumentCreateControl.ascx (istanza docCtrl As New DocumentController, :13).
  • Control di dettaglio (raccolta campi): DocManagementControl.DocumentDetail (area/rack/shelf/folder, descrizione, note, sito, categoria, tag, allegato, date validità).
  • Gate di accesso: validazione lato UI (Me.Validate) prima di procedere; autenticazione di sessione (WS.SessionContact, WS.CurrentTenant).

Sequenza principale (main sequence)

  1. Operatore compila il wizard (dettaglio, ubicazione, allegato, tag, attributi) e preme Salva.
  2. DocumentCreateControl.ascx.vb → btnSalva_Click (:1243) → CreateDocument() (:1002) → InsertDocument(autoPublish, 0, IDDocSaved) (:1005).
  3. InsertDocument (:174) costruisce il DTO Objects.Document: anagrafica (Description, Notes), ubicazione (Area/Rack/Shelf/Folder), sito (DocumentSite.ID_DTO), categoria (IdCategory + Category), allegato (Attachment), validità (IsValid/ValidFrom/ValidTo/DocumentDate), tag selezionati (GetSelectedTagsID()), attributi custom generici/specifici (CustomGenericAttributes / CustomSpecificAttributes, popolati leggendo docCtrl.GetAllAttributes() / GetAttributesByCategory(...)), CreatedBy = WS.SessionContact.ID_DTO.
  4. Controllo anti-duplicato: checkNoExistDocument(doc) (:323, def :417) confronta descrizione + nome file + categoria + scadenze con i documenti esistenti via docCtrl.SelectByDescription(...). Se noExistDocument = True si procede.
  5. Dim newDocID As Integer = docCtrl.Insert(doc) (:327) → DocumentController.Insert (DocumentController.vb:16) → DirectCast(Me.DAO, IDocument_BL).Insert(dto) (:17). Me.DAO è risolto da DAOFactory.CreateDAO(enControllers.Ctrl_Document) via .NET Remoting (Activator.GetObject(GetType(IDocument_BL), ...), DAOFactory.vb:14-15) → implementazione Document_BL.
  6. Document_BL.Insert (Document_BL.vb:24): estrae la lista id-tag dal DTO (:29) e invoca il DAL DocumentDAL.DocumentDALFactory.GetDocumentDAL.Insert(...) con ~23 argomenti (:33-55), ottenendo idDoc. Poi, in un Try separato, per ogni attributo custom generico/specifico chiama GetDocumentDAL.AddDocAttribute(idDoc, IdAttribute, Name, Value) (:61, :70). Ritorna idDoc.
  7. Document_DAL.Insert (Document_DAL.vb:328):
    • Protocollo: prepara 4 parametri OUT e chiama DOC_GETNEWDOCPROTOCOL (:359); compone Protocol applicando regex/suffisso (:361-364), poi dl.ClearParameter().
    • Prepara i parametri IN del documento (descrizione, note, blob allegato PDOCUMENTFILE, sito, contatto, ubicazione, validità, PIDTAGLIST come PLSQLAssociativeArray, categoria, PSYSPROTOCOL, ecc.) + PNEWINDEX OUT (:370-453).
    • Invoca DOC_CREATEDOCUMENT (:456) e ritorna PNEWINDEX come nuovo id (:458).
  8. Oracle DOC_CREATEDOCUMENT (INFOCAD_TEST38):
    • se PDOCUMENTFILE non nullo, chiama DOC_CREATEATTACHMENT(...) → INSERT DOCS_ATTACHMENT RETURNING ID_ATTACHMENT (src);
    • INSERT DOCS_DOCUMENT (colonne anagrafiche + ID_ATTACHMENT + START_DATE = SYSDATE, SYS_PROTOCOL, USER_PROTOCOL, USER_VERSION) RETURNING ID_DOCUMENT INTO PNEWINDEX;
    • chiama DOC_ADDTAGSTODOCUMENT(PIDTAGLIST, PNEWINDEX) → INSERT DOCS_TAG_DOCUMENT (una riga per tag).
  9. Per ogni attributo custom, Document_DAL.AddDocAttribute (:2421) invoca DOC_ADDDOCATTRIBUTE (:2436) → INSERT DOCS_DOCUMENT_ATTRIBUTE RETURNING ID_DOCATTRIBUTE.
  10. Post-salvataggio (in InsertDocument/CreateDocument): recupero protocollo (GetProtocolByDocumentID, :329), salvataggio allegati secondari (AddAttachmentDoc, :336), assegnazione tenancy (SetDocumentTenancies("DOCUMENT", newDocID, ...), :351), salvataggio scadenze (DeadlineControl.SaveItemListIntoDB, :353), ingresso in workflow (CreateWorkFlowEntryPoint, :358), eventuale auto-pubblicazione, refresh cache (DocCenterHelper.EmptyFromCache/...).

API / service

  • Path interattivo: postback ASP.NET Web Forms diretto sul wizard (nessun SOAP/REST).
  • Comunicazione controller→BL: .NET Remoting — DocumentController (client) chiama IDocument_BL risolto da DAOFactory con Activator.GetObject(...) sul canale SettingsManager.CHANNEL://SERVERADDRESS/Service_Document (DAOFactory.vb:15). In esecuzione in-process/remoto secondo configurazione.

Backend

  • UI/Code-behind: DocumentCreateControl.ascx.vb (wizard creazione).
  • Controller server: Descor.Documents.DocumentControllers.DocumentController (InfocadServer/DocumentControllers/DocumentController.vb), eredita Ctrl_EntityBase.
  • Factory DAO: DocumentControllers/serv/DAOFactory.vb (Ctrl_Document → IDocument_BL).
  • Business Layer: Descor.Documents.DocumentBL.Document_BL (InfocadServer/DocumentBL/Document_BL.vb).
  • DAL: DocumentDAL.OracleODP.Document_DAL (InfocadServer/DocumentDAL/OracleODP/Document_DAL.vb), ottenuto via DocumentDALFactory.GetDocumentDAL.
  • Pattern DAL: Using dl As DataLayer = New DataLayer(My.Settings.ConnectionName) → dl.Parameters.Add(OracleParameter...) → dl.ExecuteNonQueryStoredProcedure("DOC_CREATEDOCUMENT"); id di ritorno via parametro OUT PNEWINDEX.

Query / stored procedure

Passo Stored procedure (Oracle INFOCAD_TEST38) Chiamata da (DAL)
Generazione protocollo di sistema DOC_GETNEWDOCPROTOCOL (4 OUT) Document_DAL.vb:359
Creazione documento (INSERT DOCS_DOCUMENT) DOC_CREATEDOCUMENT (OUT PNEWINDEX) Document_DAL.vb:456
INSERT allegato principale (DOCS_ATTACHMENT) DOC_CREATEATTACHMENT (interna a DOC_CREATEDOCUMENT) DOC_CREATEDOCUMENT src
INSERT associazioni tag (DOCS_TAG_DOCUMENT) DOC_ADDTAGSTODOCUMENT (interna a DOC_CREATEDOCUMENT) DOC_CREATEDOCUMENT src
INSERT attributi custom (DOCS_DOCUMENT_ATTRIBUTE) DOC_ADDDOCATTRIBUTE (OUT PNEWINDEX) Document_DAL.vb:2436

Tabelle lette (read)

  • INFOCAD_TEST38: DOCS_PROTOCOLFORMAT (formula/regex/suffisso protocollo, letta da DOC_GETNEWDOCPROTOCOL).
  • Letture di supporto UI (categoria/attributi/anti-duplicato) via DOC_GET* (es. DOC_GETDOCUMENTBYDESCRIPTION per checkNoExistDocument) — non parte della transazione di scrittura.

Tabelle modificate (write)

  • INFOCAD_TEST38: DOCS_DOCUMENT (RW — entità-radice del documento: INSERT con RETURNING ID_DOCUMENT; VERIFIED su sorgente DOC_CREATEDOCUMENT).
  • DOCS_ATTACHMENT (RW — INSERT allegato principale con blob, solo se PDOCUMENTFILE non nullo; RETURNING ID_ATTACHMENT; via DOC_CREATEATTACHMENT).
  • DOCS_TAG_DOCUMENT (RW — INSERT n righe di associazione tag↔documento; via DOC_ADDTAGSTODOCUMENT).
  • DOCS_DOCUMENT_ATTRIBUTE (RW — INSERT attributi custom generici/specifici; via DOC_ADDDOCATTRIBUTE).

Validazione

  • Lato UI: Me.Validate prima di CreateDocument (:1245, :1258); controllo anti-duplicato checkNoExistDocument (descrizione + file + categoria + scadenze, :417); se il documento esiste già l'INSERT non viene eseguito.
  • Lato BL: la creazione degli attributi custom è in un Try isolato (Document_BL.vb:57-79): un errore sugli attributi viene loggato ma NON annulla il documento già inserito.
  • Lato DB: DOC_CREATEDOCUMENT esegue l'attachment solo se il blob non è nullo (IF NOT PDOCUMENTFILE IS NULL); nessun controllo di esistenza tabella (SQL statico).

Side effects

  • Assegnazione protocollo di sistema (DOC_GETNEWDOCPROTOCOL + DOCS_PROTOCOLFORMAT) iniettato in SYS_PROTOCOL.
  • Stamping CREATEDBY = WS.SessionContact.ID_DTO, START_DATE = SYSDATE.
  • Assegnazione tenancy documento (SetDocumentTenancies, :351).
  • Salvataggio scadenze (DeadlineControl.SaveItemListIntoDB, :353).
  • Ingresso in workflow (CreateWorkFlowEntryPoint, :358) ed eventuale auto-pubblicazione (RunWorkFlow, :372) sul path Salva e pubblica.
  • Salvataggio allegati secondari (AddAttachmentDoc, :336).
  • Refresh cache DocCenter (DocCenterHelper.EmptyFromCache/UpdateCache).
  • Sistema di alert/mailing (ProcessAlertSystem, :1248) se configurato.

Percorsi alternativi / di errore

  • Upload massivo / processi: UploadProcessControl.ascx.vb:193 → InsertDocument(doc) → docCtrl.Insert(doc) (:690 circa) — stessa DOC_CREATEDOCUMENT.
  • Wizard alternativi (Temp): DocumentInsertControl.ascx / DocumentInsertControlNew.ascx → InsertDocument(...) → docCtrl.Insert.
  • Contatto mancante: se CreateWorkFlowEntryPoint non trova il contatto, il documento appena creato viene cancellato fisicamente (docCtrl.FinalDelete(newDocID) + eliminazione scadenze, :382-383).
  • Inserimento da cancellato (RequestCenter/custom): se InsertCancelled, subito dopo l'insert si esegue docCtrl.LogicalDelete(newDocID) (:365).
  • Errore generico: eccezione catturata e loggata via InfocadTraceWrapper.CreateError (:1253); il DAL logga con ExceptionLogger.LogException e rilancia (Document_DAL.vb:462-463).
  • Aggiornamento (controprova non distruttiva): Document_DAL.Update → DOC_UPDATEDOCUMENT (Document_DAL.vb:1500); rinnovo/revisione: DOC_RENEWDOCUMENT (:1771) / DOC_REVIEWDOCUMENT (:1902).

Diagramma di sequenza

sequenceDiagram
    actor Op as Operatore DocCenter
    participant UI as DocumentCreateControl.ascx
    participant CB as InsertDocument (code-behind)
    participant DC as DocumentController.Insert
    participant BL as Document_BL.Insert
    participant DAL as Document_DAL.Insert
    participant DB as Oracle INFOCAD_TEST38

    Op->>UI: compila wizard + click Salva
    UI->>CB: btnSalva_Click -> CreateDocument -> InsertDocument
    CB->>CB: costruisce DTO Document (+ tag, attributi)
    CB->>CB: checkNoExistDocument (anti-duplicato)
    CB->>DC: docCtrl.Insert(doc)
    DC->>BL: IDocument_BL.Insert(dto)  [.NET Remoting / DAOFactory]
    BL->>DAL: GetDocumentDAL.Insert(...23 args...)
    DAL->>DB: DOC_GETNEWDOCPROTOCOL (OUT protocollo)
    DB->>DB: read DOCS_PROTOCOLFORMAT
    DAL->>DB: DOC_CREATEDOCUMENT (OUT PNEWINDEX)
    alt PDOCUMENTFILE non nullo
        DB->>DB: DOC_CREATEATTACHMENT -> INSERT DOCS_ATTACHMENT
    end
    DB->>DB: INSERT DOCS_DOCUMENT RETURNING ID_DOCUMENT
    DB->>DB: DOC_ADDTAGSTODOCUMENT -> INSERT DOCS_TAG_DOCUMENT
    DAL-->>BL: idDoc (PNEWINDEX)
    loop per attributo custom
        BL->>DAL: AddDocAttribute(idDoc, ...)
        DAL->>DB: DOC_ADDDOCATTRIBUTE -> INSERT DOCS_DOCUMENT_ATTRIBUTE
    end
    BL-->>DC: idDoc
    DC-->>CB: newDocID
    CB->>CB: protocollo, tenancy, scadenze, workflow, cache

Matrice di tracciabilità (file:riga)

Livello Elemento File:riga
UI trigger btnSalva_Click → CreateDocument() InfocadWeb/.../DocCenterWeb/UserControls/Custom/DocumentCreateControl.ascx.vb:1243,1246
UI trigger (pubblica) btnSalvaPubblica_Click → CreateDocument(True) DocumentCreateControl.ascx.vb:1257,1259
Code-behind CreateDocument → InsertDocument DocumentCreateControl.ascx.vb:1002,1005
Code-behind InsertDocument (build DTO) DocumentCreateControl.ascx.vb:174
Validazione checkNoExistDocument DocumentCreateControl.ascx.vb:323,417
Chiamata controller docCtrl.Insert(doc) DocumentCreateControl.ascx.vb:327
Controller DocumentController.Insert → Me.DAO InfocadServer/DocumentControllers/DocumentController.vb:16-17
Wiring controller→BL DAOFactory Ctrl_Document → IDocument_BL InfocadServer/DocumentControllers/serv/DAOFactory.vb:14-15
BL Document_BL.Insert → GetDocumentDAL.Insert InfocadServer/DocumentBL/Document_BL.vb:24,33
BL loop attributi → AddDocAttribute Document_BL.vb:61,70
DAL Document_DAL.Insert (protocollo) InfocadServer/DocumentDAL/OracleODP/Document_DAL.vb:328,359
DAL ExecuteNonQueryStoredProcedure("DOC_CREATEDOCUMENT") Document_DAL.vb:456
DAL ritorno PNEWINDEX Document_DAL.vb:458
DAL AddDocAttribute → DOC_ADDDOCATTRIBUTE Document_DAL.vb:2421,2436
SP DOC_CREATEDOCUMENT INSERT DOCS_DOCUMENT Oracle user_source (INFOCAD_TEST38)
SP DOC_CREATEATTACHMENT INSERT DOCS_ATTACHMENT Oracle user_source
SP DOC_ADDTAGSTODOCUMENT INSERT DOCS_TAG_DOCUMENT Oracle user_source
SP DOC_ADDDOCATTRIBUTE INSERT DOCS_DOCUMENT_ATTRIBUTE Oracle user_source
SP DOC_GETNEWDOCPROTOCOL read DOCS_PROTOCOLFORMAT Oracle user_source

Evidenza (INLINE)

Vedi sezione seguente (corpo evidenza restituito anche come evidence_markdown).

Confidence

  • VERIFIED sul cuore del flusso: UI DocumentCreateControl → DocumentController.Insert → Document_BL.Insert → Document_DAL.Insert → DOC_CREATEDOCUMENT, con INSERT su DOCS_DOCUMENT (+ DOCS_ATTACHMENT, DOCS_TAG_DOCUMENT) confermato sul sorgente della stored procedure (user_source, INFOCAD_TEST38). Almeno 2 tipi di evidenza: (1) codice VB.NET UI/BL/DAL, (2) sorgente Oracle PL/SQL delle SP, (3) catalogo DB (database-catalog.json).
  • SUPPORTED sul wiring controller→BL via .NET Remoting (DAOFactory, Activator.GetObject): confermato in DAOFactory.vb ma l'implementazione concreta Document_BL è risolta a runtime.
  • Forward/Reverse concordi: la risalita da DOCS_DOCUMENT ← DOC_CREATEDOCUMENT ← Document_DAL.Insert ← Document_BL.Insert ← DocumentController.Insert ← DocumentCreateControl combacia con la discesa.

Open questions

  • La generazione/incremento del contatore di protocollo: DOC_GETNEWDOCPROTOCOL legge DOCS_PROTOCOLFORMAT ma la sequenza SEQ_DOCS_PROTOCOL risulta commentata nel sorgente; da verificare come viene effettivamente incrementato il progressivo di protocollo.
  • DOC_ADDTAGSTODOCUMENT contiene chiamate commentate a DOC_REFRESHTAGWEIGHT: il "peso" dei tag non viene aggiornato in fase di creazione (comportamento voluto?).
  • Attributi custom (DOCS_DOCUMENT_ATTRIBUTE) inseriti fuori transazione atomica rispetto a DOCS_DOCUMENT: un fallimento parziale lascerebbe il documento senza attributi (log-only).