Questa è una vecchia versione del documento!

Indice

INTEGRAZIONE BONITA 7 - DOCWAY 4

INTEGRAZIONE BONITA 7 - DOCWAY 4

Versione Bonita BPM supportata: 7.1.4 con JAVA 8
La versione di java non corretta genera conflitti tra le dipendenze di xerces e xstream

Installazione Bonita

Installare Bonita BPM tramite il Bundle con Tomcat o il singolo WAR (riferirsi alla guida all'installazione di Bonita per maggiori dettagli)
1. Guida Interna
Copiare il file 3diws-bonita-connectors.properties all'interno della directory [BONITA_HOME]/webapps/bonita/WEB-INF/classes
Configurare i logs di Bonita
Disabilitare il SecurityFilter su Bonita, per permettere l'apertura dei form dei flussi da iFrame su DocWay
Verificare eventuali configurazioni aggiuntive da attivare

File 3diws-bonita-connectors.properties

Di seguito è riportato un esempio di contenuto del file 3diws-bonita-connectors.properties (utilizzato da tutti i connettori sviluppati da 3DI per operare sugli archivi eXtraWay - chiamate ai 3diWS)

# URL dei 3diws da utilizzare
xwWsUrl=http://localhost:8080/3diws/services/eXtraWay

# Eventuale username e password da utilizzare in caso di autenticazione ai webservice (se abilitata)
xwWsAuthUser=3diws
xwWsAuthPassword=admin

# Host e posta di eXtraWay
xwHost=127.0.0.1
xwPort=4859

# Utente (ed eventuale password) da utilizzare in fase di init (caricamento diritti, ...). Questo parametro potrebbe essere ridefinito da
# alcuni connettori (es. SavePostit imposta l'operatore che effettivamente è l'autore del commento)
xwUser=xwservice
xwPassword=

# Nome dell'archivio DocWay da utilizzare
xwDb=xdocwaydoc

# Nome dell'archivio ACL da utilizzare
aclDb=acl

# Encoding dei frammenti XML (default UTF-8)
encoding=UTF-8
# Dimensione della generica pagina dei titoli (default 10)
titlePageSize=10
# Dimensione della generica pagina del vocabolario (default 10)
indexPageSize=10

Configurazione dei LOGS su Bonita

Per integrare all'interno dei logs di Bonita eventuali logs di connettori o script groovy presenti all'interno dei flussi occorre modificare il file logging.properties presente all'interno della directory [BONITA_HOME]/conf e aggiungere le righe di seguito:

Una possibile configurazione di default è la seguente:

# Set log level to "finest" for Groovy script
org.bonitasoft.groovy.script.handlers = 5bonita.org.apache.juli.FileHandler
org.bonitasoft.groovy.script.level = FINEST

# Reuse Bonita log handler (file bonita.log) for org.mycompany.connector loggers
it.tredi.bonita7.handlers = 5bonita.org.apache.juli.FileHandler
it.tredi.bonita7.level = FINEST

In ambiente di produzione si consiglia di impostare il livello di log a INFO in modo da non compromettere le performance per l'eccessiva scrittura di logs.

Verificare che l'handler specificato (5bonita.org.apache.juli.FileHandler) sia definito all'interno del file logging.properties.

Disattivazione del SecurityFilter di Bonita

Per permettere l'apertura dei form di flussi di Bonita da iFrame su DocWay occorre disattivare il SecurityFilter sulla webapp di Bonita.

Aprire il file web.xml di Bonita ([TOMCAT_HOME]/webapps/bonita/WEB-INF/web.xml)
Commentare il filtro SecurityFilter

...
<!-- Security Filter -->
<!--filter>
    <filter-name>SecurityFilter</filter-name>
    <filter-class>org.bonitasoft.console.common.server.login.filter.SecurityFilter</filter-class>
</filter-->
...
<!--filter-mapping>
    <filter-name>SecurityFilter</filter-name>
    <url-pattern>/portal/homepage</url-pattern>
    <url-pattern>/login.jsp</url-pattern>
</filter-mapping-->
...

Riavviare il Tomcat di Bonita

IMPORTANTE: Bonita e DocWay devono essere installati e raggiungibili attraverso lo stesso host. In caso contrario non sarebbe possibile attivare l'autenticazione integrata tramite passaggio di COOKIE

Configurazioni aggiuntive

Chiusura automatica del Form

E' possibile attivare la chiusura automatica del form di esecuzione di un task su DocWay in caso di successo, applicando la seguente procedura):

Modificare il file [BONITA_HOME]/webapps/bonita/WEB-INF/classes/html/bonita_default_confirm.html (aggiungere dentro lo script “/bonita/portal/scripts/3di/humantasksaved.js”)

<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html dir="ltr" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="description" content="Bonita Forms Application" />
<link href="css/bonita_form_confirm.css" rel="stylesheet" type="text/css" />
</head>
<body>
  <div class="bonita_form_container">
    <div id="bonita_form_confirm_message" class="bonita_form_confirm_message"></div>
    <div id="bonita_form_confirm_todolist" class="bonita_form_confirm_todolist"></div>
 -->   <script type="text/javascript" src="/bonita/portal/scripts/3di/humantasksaved.js"></script>  <--
  </div>
</body>
</html>

Creare la directory 3di: mkdir [BONITA_HOME]/webapps/bonita/portal/scripts/3di
Creare il file [BONITA_HOME]/webapps/bonita/portal/scripts/3di/humantasksaved.js (impostare il corretto URL a DocWay come visualizzato da browser nel sorgente visualizzato di seguito)

var docwayHost = "http://HOST[:PORT]/DocWay4";

try {
    var parentHtml = $(window.top.document).find("html");
}
catch(e) {
    console.log(e);
    document.location.href = docwayHost + "/docway/bonitaFormBack.html";
}

Dimensione massima allegati su Bonita Portal

Per modificare la dimensione massima degli allegati gestiti su Bonita Portal occorre seguire la procedura di seguito:

Aprire il file [BONITA_HOME]/bonita/client/tenants/1/conf/forms-config.properties
Aggiornare il valore associato alla property form.attachment.max.size
Aprire il file [BONITA_HOME]/bonita/client/platform/tenant-template/conf/forms-config.properties
Aggiornare il valore associato alla property form.attachment.max.size
Riavviare Bonita BPM

Sessione utente su Bonita Portal

Modificare la durata della sessione utente sul file [BONITA_HOME]/bonita/engine-server/conf/tenants/1/bonita-tenant-community-custom.properties

bonita.tenant.session.duration=28800000

Modificare la sessione utente sul file web.xml della webapp bonita. Nel caso non esista l'elemento session-config aggiungerlo come ultimo elemento figlio di web-app

<session-config>
    <session-timeout>480</session-timeout>
</session-config>

Riavviare Bonita BPM

Differenze con integrazione ver. 5.10

Di seguito sono elencate le differenze principali rispetto all'integrazione con Bonita ver. 5.10:

Le variabili globali definite sul processo sono solo le seguenti (qualsiasi altra informazione relativa al documento che deve essere mostrata sul flusso dovrà essere caricata tramite connettore all'avvio del processo):
- dw__nrecord [STRING]: nrecord del documento al quale viene agganciato il workflow
- dw__cod_persona [STRING]: matricola dell'utente che avvia il workflow (iniziatore del workflow)
- dw__cod_uff [STRING]: codice dell'ufficio di appartenenza dell'utente che avvia il workflow
Il form di esecuzione di un task di processo non è più visualizzato con un componente sviluppato da 3DI, ma attraverso una chiamata alla webapp di Bonita BPM che restituisce direttamente l'HTML da visualizzare (in questo modo non ci saranno più limitazioni nella definizione dei form del flusso).
- Piena compatibilità con i form definiti in modalità 6.x. Sui nuovi form realizzati tramite UI Designer occorre verificare come gestire il ritorno post submit del form
L'anagrafica delle persone interne è completamente replicata sul database di Bonita. Ogni operatore può accedere sia a DocWay che a Bonita con lo stesso username e password
- Il primo caricamento del form di esecuzione di un task da DocWay richiederà l'inserimento dello username e password per l'autenticazione su Bonita BPM. Per tutta la durata della sessione utente non sarà più richiesto l'inserimento di username e password.
- La possibilità di accedere alla webapp di Bonita BPM fornisce la possibilità di avanzare i flussi attivi o amministrare i processi caricati (solo per utenti con ruolo amministratore su Bonita)
La storia delle azioni su un flusso viene registrata sul documento quando il flusso risulta concluso o annullato. Durante l'esecuzione del flusso le informazioni su azioni svolte saranno recuperate tramite una chiamata alle API di Bonita.
La chiusura dei flussi su DocWay non avviene in realtime, ma è stato sviluppato un job che verifica (attraverso chiamate alle API di Bonita) se tutti i flussi in esecuzione su DocWay risultano completati o annullati su Bonita. In caso affermativo il job aggiorna lo stato di ogni flusso su DocWay e registra la storia completa delle azioni svolte sui task del flusso.
- Implementazione necessaria per poter gestire scenari nei quali differenti applicazioni condividono uno stesso flusso. E' errato ipotizzare che l'avanzamento del flusso avvenga sempre e solo da DocWay!

Scenari di integrazione previsti

Autenticazione LDAP

LDAP aziendale preesistente utilizzato per autenticazione
DocWay si autentica su LDAP
Bonita si può sincronizzare con LDAP per mantenere aggiornata l'anagrafica utenti
Al primo accesso al form di Bonita da DocWay l'utente dovrà inserire il proprio username e password

Per l'attivazione di questo scenario occorre attivare una delle versioni a pagamento di Bonita BPM. Non è possibile installare il plugin di autenticazione e sincronizzazione LDAP sulla versione community di Bonita!

Un'alternativa all'acquisto di Bonita consiste nella configurazione “senza autenticazione”. Questo comporta che gli utenti non possano però accedere anche al Bonita Portal.

Autenticazione Tomcat

Autenticazione utenti su Tomcat (tomcat-users.xml con password MD5)
JOB su DocWay per la sincronizzazione degli utenti con il database di Bonita: Registrazione della stessa password utilizzata per l'accesso a DocWay (sul database di Bonita viene registrato il valore MD5 in base64)
DocWay si autentica su Tomcat
Al primo accesso al form di Bonita da DocWay l'utente dovrà inserire il proprio username e password

Autenticazione DB Bonita BPM

Autenticazione con DB Bonita BPM
Nessun processo di sincronizzazione utenti
DocWay si autentica su Bonita
Usename e Password degli utenti gestiti da Bonita (registrati su db Bonita)
L'accesso al form di Bonita da DocWay avviene senza che l'utente debba inserire il proprio username e password (autenticazione integrata)

L'autenticazione su DB di Bonita utilizza un modulo già integrato in DocWay per l'autenticazione utenti su DB SQL esterno. Al momento non è stata implementata l'effettiva soluzione per il DB di Bonita.

Senza Autenticazione

Autenticazione DocWay su Tomcat o LDAP/AD
Inserimento/Aggiornamento degli utenti su Bonita BPM al login di un utente su Tomcat
Stessa password su Bonita per tutti gli utenti (definita su file di properties di DocWay). L'accesso a Bonita Portal è quindi riservato ai soli amministratori dei flussi
L'accesso al form di Bonita da DocWay avviene senza che l'utente debba inserire username e password (autenticazione via SW da parte del service di DocWay e recupero del COOKIE di Bonita)
- Bonita e DocWay devono essere installati e raggiungibili attraverso lo stesso host. In caso contrario non sarebbe possibile attivare l'autenticazione integrata tramite passaggio di COOKIE
- Occorre impostare un tempo di sessione elevato su Bonita Portal in modo che la sessione utente non scada se non utilizzato durante la giornata (es. 10 ore)
Configurazioni (oltre a quelle base per l'integrazione con Bonita) su it.highwaytech.apps.xdocway.properties necessarie all'attivazione di questo scenario:
- abilitaBonitaTomcatUsersSync=no
- bonitaSync.upgradeOnLogin=si
- bonita.domain
- bonita.sessionCookieName
- bonitaSync.password

Principali properties su DocWay

Di seguito la porzione di properties relativa alle configurazione dell'integrazione con Bonita BPM ver. 7 estratte dal file it.highwaytech.apps.xdocway.properties

Settare come dominio il FQDN (Fully Qualified Domain Name) in : bonita.server_url_form e bonita.application_name_form.

Necessario per evitare problemi nella gestione dei cookie con i browser IE11 e Edge su Windows.

######################### Bonita BPM integration ############################################################################################################

#Indica se abilitare il Workflow bonita ('si', 'no' - Default = 'no')
abilitaeXtraWayWorkflow=si

# definisce le versioni di bonita installate e utilizzate da DocWay. Separare i valori da ','  
bonita.activeVersions=
#bonita.activeVersions=5,7

# Indica se abilitare o meno il JOB di CheckProtocolTask (avanzamento workflow di Bonita su protocollazione di un documento) ('si', 'no' - Default = 'si')
#abilitaCheckProtocolTask=no

######################### Bonita 6+ integration

# Parametri di connessione a Bonita per chiamate server tramite API
bonita.server_url=
#bonita.server_url=http://localhost:9080
bonita.application_name=
#bonita.application_name=bonita

# Username e password da utilizzare per le chiamate alle API di Bonita 
bonita.username=
bonita.password=

# Apertura del form di esecuzione di un task da DocWay 
# Parametri di connessione a Bonita per definizione dell'URL di caricamento del form di esecuzione di un task (url caricato dal browser dell'utente)
# N.B.: Settare come dominio il FQDN (Fully Qualified Domain Name)
#bonita.server_url_form=http://bonita_remote_url.3di.it 
bonita.server_url_form=
bonita.application_name_form=

# I parametri 'bonita.domain' e 'bonita.sessionCookieName' devono essere configurati nel caso di voglia attivare l'autenticazione integrata al form
# di Bonita Portal con stessa password per tutti gli utenti (richiede l'attivazione di 'bonitaSync.upgradeOnLogin')
# N.B.: Settare come dominio il FQDN (Fully Qualified Domain Name)
#bonita.domain=[HOSTSERVER]
#bonita.sessionCookieName=JSESSIONID
bonita.domain=
bonita.sessionCookieName=

# se abilitato elimina i dati del workflow dal db di bonita durante la rimozione del workflow da xdocwayproc ('si', 'no' - Default = 'no')
bonita.enableDeleteProcessDefinitionFromDbBonita=no

# Parametri specifici per il processo di aggiornamento degli utenti di DocWay (solo in caso di autenticazione su Tomcat) su Bonita BPM
# abilitazione del JOB di sincronizzazione utenti da tomcat-users.xml ('si', 'no' - Default = 'no')
abilitaBonitaTomcatUsersSync=no
# Percorso assoluto al file tomcat-users.xml. Se impostato la procedura di sincronizzazione non viene avviata dopo ogni sleep ma solo se effettivamente il file
# tomcat-users è stato modificato dopo l'ultima esecuzione del processo di sincronizzazione utenti con Bonita. 
#bonitaSync.tomcatUsers.absolute.path=
# Eventuale nome del gruppo al quale associare gli utenti su Bonita (se si specifica il nome di un gruppo occorre indicare anche il ruolo - bonitaSync.addUser.roleName)
# CASE SENSITIVE
bonitaSync.addUser.groupName=
# Eventuale nome del ruolo al quale associare gli utenti su Bonita (se si specifica il nome di un ruolo occorre indicare anche il gruppo - bonitaSync.addUser.groupName)
# CASE SENSITIVE
bonitaSync.addUser.roleName=
# Parametri necessari alla correzione della password su DB di Bonita (MD5.MD5.base64 -> MD5.base64). Occorre attivare questi parametri solo se la password
# registrata su tomcat-users.xml è MD5.
# Versione di Bonita utilizzata
bonitaSync.BonitaVersion=7
# Parametri di connessione al database SQL
#bonitaSync.driverClassName=
#bonitaSync.connectionUrl=
#bonitaSync.dbUser=
#bonitaSync.dbPassword=
# Query per il recupero e aggiornamento della password su DB
bonitaSync.sqlSelectPassword=SELECT password FROM user_ WHERE username = '%USERNAME%';
bonitaSync.sqlUpdatePassword=UPDATE user_ SET password = '%PASSWORD%' WHERE id = %USERID%;

# Abilita l'inserimento/modifica degli utenti su Bonita BPM in fase di login a DocWay da parte di un utente (richiede che 'abilitaBonitaTomcatUsersSync' non 
# sia attivato: "abilitaBonitaTomcatUsersSync=no").
# Viene registrata la stessa password per tutti gli utenti (property 'bonitaSync.password'). Se si attiva questa modalita' tutti gli utente su Bonita avranno la 
# stessa password e quindi non sara' possibile consentire l'accesso a Bonita Portal agli utenti ma solo agli amministratori dei flussi 
# ('si', 'no' - Default = 'no')
bonitaSync.upgradeOnLogin=no

# Password da registrare su DB di Bonita per tutti gli utenti in caso di sincronizzazione al login su DocWay (questo parametro non viene preso in considerazione
# dal processo di sincronizzazione con Tomcat users). 
bonitaSync.password=

# URL all'applicazione bonita7view (utilizzata per la visualizzazione grafica dei flussi con indicazione dell'avanzamento sui task). Se non impostato alcun
# url la funzionalita' di preview del flusso non sara' disponibile all'operatore. 
# Necessita l'installazione e configurazione della webapp bonita7view
bonitaViewUrl=

#############################################################################################################################################################

Disegno di flussi

IMPORTANTE: Viene garantita la compatibilità (in integrazione con DocWay4) dei flussi generati su Bonita Studio 7.1.4 e funzionanti sul Portal Bonita

Per il disegno dei flussi si consiglia di:

Seguire le linee guida previste dal BPMN 2.0 (sito BPMN);
Non aggiungere connettori ai task umani. In questo modo si ha come vantaggio il fatto che tutti i task eseguiti da operatori non comporteranno tempi di attesa proporzionali all'esecuzione di eventuali connettori.
- BPMN2 prevederebbe inoltre che esista uno ed un solo connettore per ogni task per evitare problemi di inconsistenza dei dati in caso di doppia esecuzione di un task a causa di un precedente errore su un connettore
Prevedere la gestione degli errori per tutti i task non umani (esecuzione di connettori o script groovy) in modo da evitare blocchi irreversibili sul flusso.

In allegato alla pagina è stato caricato un esempio di flusso disegnato (con relativo bar per l'inclusione sulla webapp di Bonita):

bar-flusso-di-prova.zip (scompattare il file .zip e caricare i 2 file .bar inclusi sulla webapp di Bonita per il test funzionale del flusso)
bos-flusso-di-prova.zip (scompattare il file .zip e caricare il file .bos incluso su Bonita Studio per l'edit del flusso

Flussi implementati

Tutti i flussi sviluppati per i clienti sono stati caricati su GitLAB all'interno del progetto 'flussi-bonita7' (gruppo 'bonita7'). Per informazioni sulla procedura di creazione/modifica di flussi si rimanda al file README.MD del progetto.

Connettori sviluppati

Tutti i connettori (stabili e snapshot) sviluppati vengono caricati direttamente sull'FTP per essere resi disponibili ai cliente tramite i relativi JOB di Jenkins: ftp://ftp.3di.it/releases/bonita7/connectors

Anche tutte le dipendenze JAR necessarie all'utilizzo dei connettori sono caricate sull'FTP: Dipendenze JAR

Occorre importare tutte le dipendenze JAR all'interno di Bonita Studio prima di poter procedere con il disegno di un flusso basato su eXtraWay

Nella tabella seguente sono elencati tutti i connettori realizzati (con il link al relativo sito MAVEN per i dettagli delle versioni):

NOME	TIPO	DESCRIZIONE
GrantRight	Connettore	Assegnazione di un documento ad una persona/ufficio/ruolo in RPA/CC/CDS
LinkProcessToDocument	Connettore	Aggancio di una istanza di processo di Bonita BPM ad un documento di DocWay (in caso di avvio di un processo al di fuori di DocWay)
LoadDocument	Connettore	Caricamento di un documento XML da eXtraWay
LoadFileIdsByLibroFirma	Connettore	Recupero degli identificativi dei files per i quali e' richiesta la firma secondo le modalita' del libro firma di DocWay
SavePostIt	Connettore	Aggiunta annotazione a documento su DocWay
ACLOfficeResolver	Filtro Attori	Recupero di tutte le persone appartenenti ad un ufficio
AddCC	Connettore	Aggiunta di una persona interna ai CC di un documento
~~AvepaDirigenteCC~~	Connettore	Data la matricola di un operatore, recupero il ruolo del dirigente del proprio ufficio e lo assegna in CC ad un documento (DEPRECATO - utilizzata la lettura di properties per il recupero del dirigente e GrantRight per l'aggiunta in CC)
~~AvepaDirigenteRemoveCC~~	Connettore	Data la matricola di un operatore, recupero il ruolo del dirigente del proprio ufficio e lo rimuove dai CC di un documento (DEPRECATO - utilizzata la lettura di properties per il recupero del dirigente e DenyRight per l'eliminazione dai CC)
DenyRight	Connettore	Eliminazione di un assegnatario (persona/ufficio/ruolo in RPA/CC/CDS) da un documento
ExtractFilesList	Connettore	Recupero di tutti i files caricati sul documento
InserisciInLibroFirma	Connettore	Il connettore si occupa di marcare “da firmare” determinati file caricati su un documento (inserimento in libro firma di files allegati al documento)
LoadFileIdsByPos	Connettore	Recupero degli identificativi dei files allegati ad un documento in base alla loro posizione sul documento
LoadFileIdsByTitle	Connettore	Recupero degli identificativi dei files allegati ad un documento in base al loro titolo sul documento
RimuoviDaLibroFirma	Connettore	Il connettore si occupa di rimuovere il tag “da firmare” su determinati file caricati su un documento
SaveDocument	Connettore	Salvataggio di un documento su eXtraWay
ACLRoleResolver	Filtro Attori	Dato il codice di un ruolo resistuisce tutte le persone che ne fanno parte
~~AvepaDirigenteResolver~~	Filtro Attori	Recupera come attori per il task tutti gli utenti aventi il ruolo di dirigente dell'area di appartenenza dell'operatore indicato. (DEPRECATO - con la gestione delle properties per la definizione dei flussi viene utilizzato il classico ACLRoleResolver)
AclGetPersonaInternaByLogin	Connettore	Recupero di una persona interna data la login principale (prima login impostata per l'utente in caso di multilogin) dell'utente
AclGetPersonaInternaByMatricola	Connettore	Recupero di una persona interna data la matricola dell'operatore
ProtocollaBozza	Connettore	Protocollazione di un documento in bozza
AddAttachment	Connettore	Caricamento di un allegato (file) su un documento
AclGetStrutturaInternaByCodUff	Connettore	Recupero di una struttura interna data il codice dell'ufficio
AclGetRuoloByName	Connettore	Recupero di un ruolo in base al proprio nome (in caso di ruolo non trovato o più ruoli associati al ruolo passato viene restituita eccezione)
LoadProperties	Connettore	Recupero di properties da files presenti nel classpath oppure specificati con Path assoluti (in caso di errore nel caricamento viene restituita eccezione). Seguendo l'ordine dei files le properties già esistenti verranno sovrascritte.
ACLUserResover	Filtro Attori	Data la matricola di una persona interna restituisce il suo identificativo su Bonita
LoadPropertyValue	Connettore	Caricamento di una specifica property (singolo valore) presente all'interno di un file di properties del flusso

Note sullo sviluppo di connettori

Per lo sviluppo di connettori e filtri su attori sono stati creati 2 archetipi per facilitare le attività di sviluppo.

Connettore

<dependency>
  <groupId>it.tredi.bonita7</groupId>
  <artifactId>xwConnectorArchetype</artifactId>
  <version>1.1.0</version>
  <type>pom</type>
</dependency>

Filtro Attori

<dependency>
  <groupId>it.tredi.bonita7</groupId>
  <artifactId>xwFilterArchetype</artifactId>
  <version>1.1.0</version>
  <type>pom</type>
</dependency>