Salvataggio di servizi per gli oggetti di business condivisi

Gli aggiornamenti agli oggetti di business condivisi vengono salvati automaticamente quando la sincronizzazione automatica è abilitata per il processo o l'istanza del servizio o esplicitamente quando viene richiamato il metodo save . Utilizzare i servizi di salvataggio per eseguire controlli di convalida, calcoli o controlli di accesso sull'oggetto di business condiviso durante la gestione del salvataggio. È possibile includere la gestione degli errori in un processo o servizio per rilevare ed elaborare gli errori che si verificano durante la convalida dei dati.
Un servizio di salvataggio è un flusso di servizi richiamato dal sistema dopo l'unione dei dati dall'oggetto di business condiviso e prima del salvataggio delle modifiche. Il servizio di salvataggio viene avviato dal sistema come parte della gestione di salvataggio e unione prima che gli aggiornamenti agli oggetti di business condivisi vengano salvati nel database. Creare un servizio di salvataggio per le seguenti operazioni:
  • Convalidare i dati aggiornati sul client. La convalida può restituire un oggetto di convalida.
  • Eseguire i calcoli basati sui dati immessi.
  • Applicare un risultato di unione alternativo. Se un'altra versione del business object condiviso viene salvata mentre il servizio di salvataggio è in esecuzione, il risultato dell'unione viene ricalcolato e il servizio di salvataggio viene riavviato.
Attenzione: più utenti o attività di sistema possono aggiornare gli oggetti di business condivisi contemporaneamente. Ad esempio, user1 desidera salvare modifiche a un oggetto di business condiviso e il servizio di salvataggio viene avviato. Tuttavia, prima di salvare le modifiche nel database, user2 salva una nuova versione dell'oggetto di business condiviso. In tal caso, il sistema richiama la nuova versione da user2, unisce le modifiche da user1e quindi avvia nuovamente il servizio di salvataggio. Pertanto, non è possibile presumere che la versione dell'oggetto di business condiviso sia persistente quando un servizio di salvataggio non restituisce alcun errore di convalida.

Variabili del servizio

Un servizio di salvataggio ha le seguenti variabili di input e output:
Variabili di input
Tabella 1. Variabili di input per i servizi di salvataggio
Variabile Descrizione
object (shared business object type) Il valore dell'oggetto di business condiviso da salvare. È possibile aggiungere la logica al servizio di salvataggio per manipolare il valore della variabile durante l'operazione di salvataggio, ad esempio per calcolare i totali basati sui dati aggiornati.
baseVersion (shared business object type) Il valore dell'oggetto di business condiviso prima che fosse modificato. Questo valore è null quando viene salvata la prima versione dell'oggetto di business condiviso.
latestVersion (shared business object type) Il valore più recente dell'oggetto di business condiviso salvato nel database. Se questo valore è diverso dal valore della variabile baseVersion , le modifiche sono state applicate a una versione precedente dell'oggetto di business condiviso e il sistema ha unito le relative modifiche con la versione più recente.
changes (BPMBOPropertyChange business object type) Un elenco che contiene le singole modifiche apportate al valore dell'oggetto di business condiviso. Ogni elemento nell'elenco ha le seguenti proprietà:
property (String)
La variabile modificata. Il formato indica quale variabile nell'oggetto di business condiviso è stata modificata.
  • propertyName : La variabile propertyName è stata modificata.
  • boPropertyName.propertyName : La variabile di tipo complesso boPropertyName di un tipo che contiene una variabile propertyName che è stata modificata.
  • listPropertyName[n ] : La variabile di elenco listPropertyName contiene un elemento dell'elenco che è stato modificato. Il numero, n, indica la voce dell'elenco modificata.
  • .@metadata.key La variabile di tipo complesso sboPropertyName che fa riferimento a un tipo di oggetto aziendale condiviso in cui è stato modificato il valore
  • listPropertyName.listLength( ) : La variabile dell'elenco listPropertyName in cui è stata modificata la lunghezza dell'elenco
oldValue (Any)
Il valore precedente della variabile.
newValue (Any)
Il nuovo valore della variabile.
Variabili di output
Tabella 2. Variabili di output per i servizi di salvataggio
Variabile Descrizione
validationErrors (BPMBOValidationError business object type) L'elenco degli errori di convalida. Se il servizio o il flusso di servizi non completa la variabile o viene restituito un elenco vuoto, l'oggetto di business condiviso viene considerato valido e viene salvato nel database. Tuttavia, in alcune circostanze, l'oggetto di business condiviso potrebbe non essere valido nonostante non venga restituito un errore. Per ulteriori informazioni, vedere Gestione degli errori.
Se viene restituito un elenco di errori, l'oggetto di business condiviso non è valido e viene generato un errore. Ogni elemento nell'elenco ha le seguenti proprietà:
property (stringa)
Il nome della variabile non è valido. Utilizzare lo stesso formato utilizzato per l'oggetto di business BPMBOPropertyChange .
errorCode (stringa)
Un codice da utilizzare per gestire l'errore in modo programmatico in un processo o in un servizio.
errorText (stringa)
Testo del messaggio che può essere visualizzato agli utenti se l'errore si verifica al runtime. È anche possibile fornire versioni tradotte del messaggio di errore.

Salva esempi di servizio

Un oggetto di business condiviso di tipo cliente viene utilizzato nei seguenti esempi. Contiene le seguenti variabili:
  • givenName (Stringa): il nome fornito del cliente
  • cognome (stringa): il cognome del cliente
  • address (Indirizzo): l'indirizzo del cliente
  • dateOfBirth (Data): data di nascita del cliente
  • status (Stringa): lo stato del cliente, ad esempio nuovo, oro o platino
  • creditScore (Decimale): l'indice di affidabilità creditizia del cliente
Esempio: verifica che una variabile non sia stata modificata
È possibile verificare che una variabile, ad esempio la data di nascita, in un oggetto di business condiviso non sia stata modificata dopo essere stata inizialmente impostata. È possibile utilizzare uno script del server nel servizio di salvataggio per la verifica.
Lo script di esempio esegue l'iterazione sull'elenco delle modifiche. Se il valore della variabile dateOfBirth viene modificato, lo script controlla che il vecchio valore non sia nullo. Se non è null, la variabile è stata modificata dall'utente e un errore di convalida viene aggiunto alla variabile validationErrors .
for(var i = 0; i < tw.local.changes.listLength; i ++) {
    var change = tw.local.changes[i];
    if(change.property == "dateOfBirth" && change.oldValue != null) {
        if(tw.local.validationErrors == null) {
            tw.local.validationErrors = new tw.object.listOf.BPMBOValidationError();
        }

        var validationError = new tw.object.BPMBOValidationError();
        validationError.property = change.property;
        validationError.errorText = "The date of birth must not be changed.";
        tw.local.validationErrors[tw.local.validationErrors.listLength] = validationError;
    }
}
Esempio: verifica delle autorizzazioni utente
È possibile avere variabili nel proprio oggetto di business condiviso che possono essere modificate solo da una serie specifica di utenti. In questo caso, il servizio di salvataggio deve controllare se l'utente che ha apportato le modifiche è stato autorizzato a farlo. Ad esempio, lo stato di un cliente può essere modificato solo da un capo team.
Il seguente script del server di esempio mostra come controllare le autorizzazioni utente. Lo script determina se l'utente corrente è un membro del team leader del team. Se l'utente non è un componente del team, lo script esegue l'iterazione sull'elenco di modifiche. Se è presente un elemento per la variabile status , il valore è stato modificato da qualcuno che non è un leader del team e viene aggiunto un errore di convalida alla variabile validationErrors .
// check if current user is team lead
var teamLeadTeam = tw.system.org.findTeamByName("Team Lead");
var isTeamLead = tw.system.user.isInTeam(teamLeadTeam);

if(!isTeamLead) {
    for(var i = 0; i < tw.local.changes.listLength; i ++) {
        var change = tw.local.changes[i];
        if(change.property == "status" && (change.oldValue != null || change.newValue != "new")) {
            if(tw.local.validationErrors == null) {
                tw.local.validationErrors = new tw.object.listOf.BPMBOValidationError();
            }

            var validationError = new tw.object.BPMBOValidationError();
            validationError.property = change.property;
            validationError.errorText = "The status must only be changed by a team lead.";
            tw.local.validationErrors[tw.local.validationErrors.listLength] = validationError;
        }
    }
}
Attenzione: quando un oggetto di business condiviso viene salvato, il servizio di salvataggio viene avviato dal sistema con le autorizzazioni dell'utente che ha causato il salvataggio. Se le modifiche agli oggetti di business condivisi vengono effettuate direttamente in un'attività di sistema, l'utente è un utente tecnico.
Esempio: unione di dati
È possibile utilizzare le variabili baseVersion e latestVersion per aggiungere la logica di unione personalizzata al servizio di salvataggio per rilevare quando viene aggiornata una versione obsoleta dell'oggetto di business condiviso.

Il seguente script del server di esempio controlla se i valori baseVersion e latestVersion sono differenti. Se differiscono, gli aggiornamenti vengono uniti. Lo script richiama quindi i diversi valori di stato dalle diverse versioni dell'oggetto di business condiviso. Il valore della variabile status viene controllato per stabilire se il valore è stato modificato in entrambe le versioni e se lo stato più recente è "platinum". In tal caso, lo stato platinum viene applicato per impedire il downgrade di un cliente da tale livello.

// check if a merge happened because an outdated version was updated
if(tw.local.baseVersion != tw.local.latestVersion) {
    var baseStatus = tw.local.baseVersion.status;
    var latestStatus = tw.local.latestVersion.status;
    var newStatus = tw.local.object.status;

    // check if the status was updated and merged
    if(newStatus != baseStatus && baseStatus != latestStatus) {
        // Make sure a downgrade from platinum does not happen
        if(latestStatus == "platinum") {
            tw.local.object.status = "platinum";
        }
    }
}
Esempio: inclusione di calcoli nei servizi di salvataggio
In un servizio di salvataggio, è possibile applicare modifiche al valore di una variabile oggetto di business condivisa. Ad esempio, è possibile richiamare un servizio nidificato che calcola l'indice di affidabilità creditizia per un cliente che viene passato nelle informazioni sul cliente, come l'indirizzo del cliente, e associare l'indice di affidabilità creditizia restituito alla proprietà tw.local.object.creditScore .

Gestione degli errori

Se uno o più richiami del servizio di salvataggio restituiscono almeno un errore di convalida, viene generato un errore. Il tipo di errore è definito dall'oggetto aziendale BPMBOSaveFailedError. È possibile aggiungere la gestione degli errori al processo o al servizio per rilevare ed elaborare gli errori che si verificano durante la convalida dei dati.
Per catturare l'errore con un evento di errore intermedio, specificare BPMBOSaveFailedError come codice di errore da catturare. Quindi, associare i dati di errore a una variabile locale. Il tipo di errore è definito dall'oggetto aziendale BPMBOSaveFailedError. L'oggetto business ha una proprietà, errors, che è un elenco di BPMBOSaveServiceValidationErrors. La proprietà errors contiene una voce per ogni oggetto di business condiviso che presenta errori di convalida durante l'esecuzione del salvataggio. L'oggetto aziendale BPMBOSaveServiceValidationErrors ha queste proprietà:
oggetto (Qualsiasi)
Contiene l'oggetto di business condiviso che non è stato possibile salvare a causa di errori di convalida.
variablePath (Stringa)
Il percorso della variabile nel contesto in cui è stato effettuato il salvataggio, automaticamente impostato dal runtime, ad esempio tw.local.customer. Si noti che, sebbene lo stesso oggetto di business condiviso possa essere indicato da più variabili o proprietà di variabili complesse, solo una di esse è impostata qui. In un processo, la sincronizzazione automatica di un oggetto aziendale condiviso può causare un salvataggio in più processi (collegati). variablePath può quindi essere null se non si fa riferimento a una variabile nel punto in cui si verifica il salvataggio.
validationErrorsBPMBOValidationError, elenco)
l'elenco degli errori di convalida restituiti dal servizio di salvataggio. Gli oggetti di business condivisi con errori di convalida sono contrassegnati come non validi. Questi oggetti di business condivisi vengono esclusi dalla sincronizzazione automatica fino a quando non viene apportata un'altra modifica e l'utente salva l'oggetto di business condiviso o viene salvato automaticamente.

Se l'errore non viene rilevato sull'attività o sul passo, viene propagato all'istanza parent. Se l'errore non viene rilevato, tutti gli aggiornamenti vengono eliminati e l'istanza viene contrassegnata come Non riuscita.

Gli oggetti di business condivisi con errori di convalida vengono esclusi dalla sincronizzazione automatica fino a quando non viene apportata un'altra modifica e l'utente salva l'oggetto di business condiviso o viene salvato automaticamente.

Esempi di gestione degli errori

Esempio: visualizzazione delle informazioni di errore per gli utenti nei servizi con interazione dell'utente lato client
Il seguente esempio mostra la logica che è possibile aggiungere ad un gestore eventi di errore per associare gli errori di convalida da un servizio di salvataggio in una struttura dati che può essere visualizzata in un Coach. Il gestore di eventi di errore mappa gli errori di convalida nella variabile sharedBOSaveError del servizio umano lato client. La variabile è del tipo BPMBOSaveFailedError.
  tw.system.coachValidation.populateFromBPMBOSaveFailedError(tw.local.sharedBOSaveError);
Per ulteriori informazioni, vedi Gestione degli errori nei servizi umani lato client.