Condividi tramite

Utilizzare i processi aziendali con il codice

Un processo aziendale consente di creare vendite, servizi e altri processi aziendali più efficienti e ottimizzati. Mediante il posizionamento di controlli speciali nella parte superiore dei moduli di tabella, viene creata una visualizzazione del processo aziendale. Gli utenti vengono guidati nelle varie fasi di vendita, marketing o processi del servizio verso il completamento. Ogni processo supporta più fasi e passaggi. È possibile aggiungere o rimuovere passaggi, modificare l'ordine delle fasi o aggiungere nuove tabelle al processo aziendale.

Puoi eseguire simultaneamente diverse istanze del processo aziendale usando la stessa riga di tabella. Gli utenti possono passare da un'istanza all'altra dei processi aziendali simultanei e riprendere il lavoro in una fase corrente del processo.

Questo argomento fornisce informazioni su come usare i processi aziendali a livello di codice.

Note

Non è necessario scrivere codice per usare i processi aziendali. Per informazioni sull'uso dell'interfaccia utente per creare e gestire processi aziendali, vedere Panoramica dei processi aziendali

Prerequisiti per il processo aziendale

Tabelle personalizzate e tabelle con moduli dell'interfaccia utente aggiornati possono partecipare al processo aziendale. Le tabelle dell'interfaccia utente aggiornate hanno la proprietà di IsAIRUpdated impostata su true.

Per abilitare una tabella per il processo aziendale, imposta la proprietà di IsBusinessProcessEnabled su true.

Important

L'abilitazione di una tabella per processo aziendale è un processo unidirezionale. Non è possibile invertirlo.

Definire il processo aziendale

Usare la finestra di progettazione del processo aziendale per definire un processo aziendale. Altre informazioni: Creare un processo aziendale

Per impostazione predefinita, una riga di processo aziendale viene creata nello stato Draft .

La definizione di un processo aziendale viene archiviata nella tabella workflow, mentre le informazioni sulla fase del processo aziendale sono archiviate nella tabella processstage.

Attivare il processo aziendale

Prima di poter utilizzare il flusso di processo, è necessario attivarlo. Per attivarlo, è necessario disporre del privilegio prvActivateBusinessProcessFlow per la tabella Workflow. Utilizza il messaggio UpdateRequest per impostare lo stato della riga di tabella Workflow su Activated. Altre informazioni: Eseguire operazioni specifiche con Update

Note

Per attivare un processo aziendale, è anche possibile usare la finestra di progettazione del processo aziendale.

Tabella del flusso di processo aziendale

Dopo aver attivato la definizione di un processo aziendale modificando lo stato della rga di tabella Workflow corrispondente o usando la finestra di progettazione del processo aziendale, viene automaticamente creata una tabella personalizzata in cui archiviare il processo aziendale attivato. Tale tabella viene denominata "<activesolutionprefix> _ <uniquename>", dove uniquename viene derivato dal nome specificato.

Ad esempio, se il nome specificato per la definizione del processo aziendale è "My Custom BPF" e si usa l'autore predefinito (new) per la soluzione attiva, il nome della tabella personalizzata creata per l'archiviazione delle istanze del processo sarà "new_mycustombpf".

Se il valore uniquename non è disponibile per la definizione di un processo aziendale, ad esempio se il processo aziendale è stato importato come parte di una soluzione da una versione precedente, il nome predefinito della tabella personalizzata sarà "\<activesolutionprefix>_bpf_<GUID_BPF_Definition>:

Important

Le righe del processo aziendale di esempio usano le tabelle di sistema per archiviare le righe dell'istanza del processo aziendale corrispondente.

Tuttavia, le nuove definizioni del processo aziendale create utilizzano le tabelle personalizzate per archiviare le proprie righe dell'istanza come descritto in precedenza.

È possibile recuperare il nome della tabella del processo aziendale usando uno dei modi seguenti:

  • Tramite l'interfaccia utente: usare l'interfaccia utente di personalizzazione per selezionare la tabella del processo aziendale:

    Sfogliare la tabella del processo aziendale usando l'interfaccia utente.

  • Tramite l'API Web: usare la richiesta seguente:

    Richiesta

    GET [Organization URI]/api/data/v9.0/workflows?$filter=name eq 'My Custom BPF'&$select=uniquename HTTP/1.1

    Response

    {  
"@odata.context":"[Organization URI]/api/data/v9.0/$metadata#workflows(uniquename)",
"value":[  
     {  
         "@odata.etag":"W/\"1084677\"",
         "uniquename":"new_mycustombpf",
         "workflowid":"2669927e-8ad6-4f95-8a9a-f1008af6956f"
     }
  ]
}

  • Tramite il servizio organizzazione: usare il codice di esempio seguente:

    QueryExpression query = new QueryExpression
{
    EntityName = "workflow",
    ColumnSet = new ColumnSet("uniquename"),
    Criteria = new FilterExpression
    {
        Conditions =
        {
            new ConditionExpression
            {
                ColumnName = "name",
                Operator = ConditionOperator.Equal,
                Values = { "My Custom BPF" }
            }
        }
    }
};
Workflow Bpf = (Workflow)_serviceProxy.RetrieveMultiple(query).Entities[0];

Note

La proprietà IsBPFEntity è true per le tabelle del processo aziendale. Per recuperare tutte le tabelle del processo aziendale nell'istanza, esegui la richiesta API Web seguente:

GET [Organization URI]/api/data/v9.0/EntityDefinitions?$select=SchemaName,LogicalName,DisplayName&$filter=IsBPFEntity eq true HTTP/1.1

Gestire la sicurezza per i processi aziendali

La tabella personalizzata che viene creata automaticamente all'attivazione di un processo aziendale per archiviare le istanze del processo aziendale è conforme al modello di sicurezza standard come per qualsiasi altra tabella personalizzata in Microsoft Dataverse. Ciò implica che i privilegi concessi per tali tabelle definiscono le autorizzazioni di runtime per gli utenti per i processi aziendali.

L'ambito della tabella del processo aziendale personalizzata è l'organizzazione. I privilegi standard per la creazione, il recupero, l'aggiornamento e l'eliminazione per questa tabeòòa definiscono le autorizzazioni per gli utenti in base ai ruoli assegnati. Per impostazione predefinita, quando viene creata la tabella personalizzata del processo aziendale, l'accesso viene concesso solo ai ruoli di sicurezza Amministratore sistema e Addetto personalizzazione sistema ed è necessario concedere in modo esplicito le autorizzazioni per la nuova tabella del processo aziendale (ad esempio, My Custom BPF) per gli altri ruoli di sicurezza in base alle esigenze.

Gestione dei ruoli di sicurezza.

Creare, recuperare, aggiornare ed eliminare righe di tabella del processo aziendale (istanze del processo)

La tabella personalizzata che viene creata automaticamente all'attivazione di una definizione di processo aziendale archivia tutte le istanze del processo per la definizione del processo aziendale. La tabella personalizzata supporta la creazione a livello di codice standard e la gestione delle righe (istanze del processo) tramite l'API Web e l'endpoint di CRM 2011.

Important

Il passaggio a un'altra istanza del processo per una riga di tabella è supportato solo tramite l'interfaccia utente (client) o a livello di codice usando le informazioni disponibili in questa sezione. Non è più possibile usare il messaggio SetProcess (SetProcess Action o SetProcessRequest) per cambiare processo a livello di codice (impostare un altro processo aziendale come istanza del processo attiva) per la riga di tabella di destinazione.

Si consideri l'esempio seguente, che include un processo aziendale tra tabelle, "My Custom BPF", con 3 fasi: S1:Account, S2:Account e S3:Contact.

Processi aziendali personalizzati.

Recuperare tutte le righe (istanze) per una tabella del processo aziendale

Se il nome della tabella del processo aziendale è "new_mycustombpf", usa la query seguente per recuperare tutte le righe (istanze del processo) per la tabella del processo aziendale:

GET [Organization URI]/api/data/v9.0/new_mycustombpfs HTTP/1.1

A questo punto, si potrebbero non ottenere istanze in risposta se non esistono. Eseguire questa richiesta dopo aver creato un'istanza della definizione del processo aziendale, come descritto più avanti in questo argomento.

Note

Per informazioni su come recuperare il nome della tabella del processo aziendale, vedi la sezione precedente Tabella del processo aziendale.

Creare una riga di tabella del processo aziendale (istanza del processo)

Crea una riga di tabella del processo aziendale (istanza del processo) a livello di codice se si vuole passare a un altro processo aziendale per una riga di tabella senza usare l'interfaccia utente.

Per creare una riga di tabella del processo aziendale, è necessario specificare i valori seguenti:

  • Associa la riga di tabella del processo aziendale a un record di entità primaria impostando la proprietà di navigazione su valore singolo con la annotazione @odata.bind. Per individuare il nome della proprietà di navigazione che si riferisce alla riga di tabella primaria per la definizione del processo aziendale, usa il documento CSDL $metadata.

  • Associa la riga di tabella del processo aziendale a una fase valida specificata nella definizione del processo aziendale, impostando la proprietà di navigazione su valore singolo con l'annotazione @odata.bind. Per individuare il nome della proprietà di navigazione (in genere activestageid) che si riferisce alla riga di fase per la definizione del processo aziendale, usa il documento CSDL $metadata.

    È anche possibile recuperare le informazioni relative a tutte le fasi di una definizione del processo aziendale usando la richiesta dell'API Web seguente, presupponendo che l'ID della definizione del processo aziendale sia 2669927e-8ad6-4f95-8a9a-f1008af6956f:

    Richiesta

    GET [Organization URI]/api/data/v9.0/processstages?$select=stagename&$filter=processid/workflowid eq 2669927e-8ad6-4f95-8a9a-f1008af6956f HTTP/1.1

    Response

    {
    "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#processstages(stagename)",
    "value": [
        {
            "@odata.etag": "W/\"858240\"",
            "stagename": "S1",
            "processstageid": "9a9185f5-b75b-4bbb-9c2b-a6626683b99b"
        },
        {
            "@odata.etag": "W/\"858239\"",
            "stagename": "S3",
            "processstageid": "a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a"
        },
        {
            "@odata.etag": "W/\"858238\"",
            "stagename": "S2",
            "processstageid": "19a11fc0-3398-4214-8522-cb2a97f66e4b"
        }
    ]
}

A questo punto, usa la richiesta seguente per creare un'istanza della definizione del processo aziendale per una riga di account (ID=a176be9e-9a68-e711-80e7-00155d41e206) e la fase attiva impostata come prima fase dell'istanza del processo, S1 (ID=9a9185f5-b75b-4bbb-9c2b-a6626683b99b):

Richiesta

POST [Organization URI]/api/data/v9.0/new_mycustombpfs HTTP/1.1 
Content-Type: application/json; charset=utf-8 
OData-MaxVersion: 4.0 
OData-Version: 4.0 
Accept: application/json 

{
    "bpf_accountid@odata.bind": "/accounts(a176be9e-9a68-e711-80e7-00155d41e206)",
    "activestageid@odata.bind": "/processstages(9a9185f5-b75b-4bbb-9c2b-a6626683b99b)"    
}

Response

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/new_mycustombpfs(cc3f721b-026e-e811-80ff-00155d513100)

Nota che se si vuole creare un'istanza della definizione del processo aziendale impostando la fase attiva non come prima fase ma come altra, è necessario specificare anche traversedpath nella richiesta. Il percorso incrociato è specificato dalla stringa delimitata da virgole degli ID delle fasi del processo che rappresentano le fasi visitate dell'istanza del processo aziendale. La seguente richiesta crea un'istanza per una riga di account (ID=679b2464-71b5-e711-80f5-00155d513100) e fase attiva impostata come seconda fase, S2 (ID=19a11fc0-3398-4214-8522-cb2a97f66e4b).

POST [Organization URI]/api/data/v9.0/new_mycustombpfs HTTP/1.1 
Content-Type: application/json; charset=utf-8 
OData-MaxVersion: 4.0 
OData-Version: 4.0 
Accept: application/json 

{
    "bpf_accountid@odata.bind": "/accounts(679b2464-71b5-e711-80f5-00155d513100)",
    "activestageid@odata.bind": "/processstages(19a11fc0-3398-4214-8522-cb2a97f66e4b)",
    "traversedpath":"9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b"   
}

Aggiornare una riga di tabella del processo aziendale (istanza del processo)

È possibile aggiornare un'istanza del processo per passare alla fase successiva o precedente, abbandonare, riattivare o terminare un'istanza del processo.

Spostamento tra le fasi

Per passare a una fase diversa, è necessario aggiornare una riga dell'istanza del processo per modificare il relativo ID della fase attiva e conseguentemente aggiornare il percorso incrociato. Si noti che durante l'aggiornamento del processo aziendale, è possibile passare solo alla fase precedente o successiva.

Per spostarsi tra le fasi, è necessario l'ID dell'istanza del processo aziendale che si vuole aggiornare. Per recuperare tutte le istanze del processo aziendale, vedi la sezione precedente Recuperare tutte le righe (istanze) per una tabella del processo aziendale.

Supponendo che l'ID dell'istanza del processo da aggiornare sia dc2ab599-306d-e811-80ff-00155d513100, usa la richiesta seguente per aggiornare la fase attiva da S1 a S2:

PATCH [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "activestageid@odata.bind": "/processstages(19a11fc0-3398-4214-8522-cb2a97f66e4b)",
    "traversedpath": "9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b"
}

Modificare lo stato di un'istanza del processo: interrompere, riattivare o terminare

L'istanza del processo può avere uno dei seguenti stati: Attivo, Terminato o Interrotto. Lo stato è determinato dalle colonne seguenti per la riga di istanza del processo:

  • statecode: visualizza lo stato dell'istanza del processo.

    valore Label
    0 Attivi
    1 Inattivi

  • statuscode: visualizza informazioni sullo stato dell'istanza del processo.

    valore Label
    1 Attivi
    2 Completate
    3 Interrotta

A questo punto, per interrompere un'istanza del processo, usare la richiesta seguente e impostare i valori statecode e statuscode in modo appropriato:

PATCH [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1   
Content-Type: application/json   
OData-MaxVersion: 4.0   
OData-Version: 4.0 
  
{ 
    "statecode" : "1", 
    "statuscode": "3" 
}

Note

È possibile interrompere un'istanza del processo in qualsiasi fase.

Analogamente, per riattivare un'istanza del processo, sostituire rispettivamente i valori statecode e statuscode nel codice precedente con i valori 0 e 1.

Infine, per impostare lo stato di un'istanza del processo su Terminato (stato possibile solo nell'ultima fase di un'istanza del processo), sostituire rispettivamente i valori statecode e statuscode nel codice precedente con 0 e 2.

Navigazione tra tabelle

Per la navigazione tra tabelle in questo esempio, è necessario impostare la fase attiva dell'istanza del processo sull'ultima fase, S3 (ID=a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a), aggiornare quindi il percorso incrociato e impostare una riga contatto come riga di tabella primaria in base alla definizione del processo aziendale.

PATCH [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1   
Content-Type: application/json   
OData-MaxVersion: 4.0   
OData-Version: 4.0 
  
{
    "activestageid@odata.bind": "/processstages(a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a)",
    "traversedpath":"9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b,a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a",
    "bpf_contactid@odata.bind": "/contacts(0e3f10b0-da33-e811-80fc-00155d513100)"
}

Eliminare una riga di tabella del processo aziendale (istanza del processo)

Usare la richiesta dell'API Web seguente:

Richiesta

DELETE [Organization URI]/api/data/v9.0/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1

Response

Se la riga esiste, si otterrà una risposta normale con stato 204 a indicare che l'eliminazione è stata completata. Se non viene rilevata la tabella, otterrai una risposta con stato 404.

Usare i messaggi RetrieveProcessInstances e RetrieveActivePath

Usa il messaggio RetrieveProcessInstances (RetrieveActivePath Function o RetrieveProcessInstancesRequest) per recuperare tutte le istanze del processo aziendale per una riga di tabella tra tutte le definizione del processo aziendale. Le istanze del processo aziendale restituite per una tabella vengono ordinate in base alla colonna modifiedon per l'istanza. Ad esempio, l'istanza del processo aziendale modificata più di recente sarà la prima riga della raccolta restituita. L'istanza di processo aziendale modificata più di recente è quella attiva nell'interfaccia utente per una riga di tabella.

Ogni riga dell'istanza del processo aziendale restituita per una riga di tabella tramite il messaggio RetrieveProcessInstances memorizza l'ID della fase attiva nella colonna processstageid che può essere usato per individuare la fase attiva e passare alla fase precedente o successiva. A tale scopo, è prima necessario trovare il percorso attivo di un'istanza del processo aziendale e le fasi disponibili nell'istanza del processo usando il messaggio RetrieveActivePath (RetrieveActivePath Function o RetrieveActivePathRequest).

Una volta avute le informazioni sulla fase attiva e su percorso attivo di un'istanza di processo aziendale, utilizza le informazioni per passare a una fase precedente o successiva nel percorso attivo. Lo spostamento in avanti delle fasi deve essere svolto in sequenza, ovvero puoi solo procedere alla fase successiva nel percorso attivo.

Per l'esempio di codice completo che dimostra l'uso di questi due metodi e lo spostamento tra le fasi tramite Servizio organizzazione, vedere Esempio: Usare i processi aziendali.

Applicare il processo aziendale durante la creazione di una riga di tabella

Questa sezione offre informazioni sul comportamento predefinito che consente di applicare automaticamente i processi aziendali a nuove righe di tabella create in Dataverse. Spiega anche come poter sostituire questo comportamento per applicare un processo aziendale a scelta a nuove righe di tabella.

Per impostazione predefinita, per una tabella con più processi aziendali correlati definiti, il sistema applica un processo aziendale nella nuova riga di tabella utilizzando la logica a più passaggi seguenti:

  1. Identificare tutti i processi aziendali applicabili alla nuova riga di tabella in base alla colonna Workflow.PrimaryEntity delle righe di definizione del processo aziendale.
  2. Identifica le definizioni del processo aziendale a cui ha accesso l'utente corrente. Per informazioni su come determinare e gestire l'accesso al processo aziendale, vedere la sezione Gestire la sicurezza per i processi aziendali illustrata in precedenza in questo argomento.
  3. Tutte le definizioni del processo aziendale nel sistema sono soggette a un ordine globale per tabella. L'ordine del processo aziendale viene archiviato nella colonna Workflow.ProcessOrder. Le definizioni del processo aziendale per una tabella sono ordinate in base a questo ordine e viene selezionata la definizione con il valore di ordinamento inferiore.
  4. Infine, se la riga di tabella viene creata da un'app aziendale (modulo dell'app), un ulteriore livello di filtro viene applicato per selezionare il processo aziendale da applicare automaticamente alla nuova riga di tabella. Quando lavorano in un'app, gli utenti possono accedere solo a tabelle, processi aziendali, visualizzazioni e moduli pertinenti per cui dispongono di accesso in virtù dei ruoli di sicurezza assegnati nell'app aziendale.
    • Se l'app aziendale non contiene alcun processo aziendale, viene applicato il processo aziendale come descritto fino al passaggio 3.
    • Se l'app aziendale include uno o più processi aziendali, sarebbero applicabili solo i processi aziendali presenti nell'app. In questo caso, quando l'utente sta lavorando in un contesto dell'app aziendale, l'elenco dei processi aziendali del passaggio 3 viene filtrato ulteriormente rispetto ai processi che fanno parte dell'app aziendale che sono presenti nel modulo dell'app e ordinati in base all'ordine di elaborazione.
    • Se in un'app aziendale non è disponibile alcun processo aziendale per la tabella o per cui l'utente ha accesso, nessun processo aziendale viene applicato per la nuova riga di tabella.

È possibile eseguire l'override della logica predefinita per ottenere i processi aziendali da applicare automaticamente alle nuove righe di tabella. A tale scopo, imposta la colonna ProcessId della tabella su uno dei valori seguenti durante la creazione di una nuova riga di tabella:

  • Imposta su Guid.Empty per ignorare l'impostazione di un processo aziendale per le nuove righe di tabella. Questa opzione potrebbe essere utile quando crei righe di tabella in blocco, ma non vuoi applicare un processo aziendale a tali righe.
  • Imposta una tabella specifica del processo aziendale (come riferimento della tabella). In questo caso, il sistema applicherà il processo aziendale specificato anziché la logica predefinita.

Se durante la creazione di una nuova riga di tabella non imposti un valore per la colonna ProcessId, il sistema applicherà la logica predefinita come descritto in precedenza.

Note

La sostituzione della logica predefinita per ottenere i processi aziendali da applicare automaticamente alle nuove righe di tabella è supportata solo a livello di codice. Non è possibile eseguire questa operazione utilizzando l'interfaccia utente.

Le colonne legacy correlate al processo (ad esempio ProcessId, StageId e TraversedPath) nelle tabelle abilitate per i processi aziendali sono già deprecati. La modifica delle colonne legacy correlate al processo per le righe di tabella di destinazione non garantisce la coerenza dello stato del processo aziendale e non è uno scenario supportato. È consigliabile usare le colonne della tabella del processo aziendale, come illustrato in precedenza nella sezione Creare, recuperare, aggiornare ed eliminare le righe di tabella del processo aziendale (istanze del processo)

L'unica eccezione consiste nel modificare a livello di codice la colonna ProcessId durante la creazione di una riga di tabella in modo da sostituire l'applicazione predefinita del processo aziendale alla nuova riga, come illustrato nella sezione precedente: Applicare un processo aziendale durante la creazione di una riga di tabella.

Supporto di programmabilità lato client per processi aziendali

Esiste un oggetto lato client che è possibile usare per interagire con i processi aziendali negli script del modulo. I processi aziendali attivano eventi lato client ogni volta che un processo viene applicato a una riga, la fase viene modificata o il relativo stato viene modificato in Active, Finished o Aborted. Altre informazioni: formContext.data.process (riferimento API client)

Numero massimo di processi, fasi e procedure

Per una tabella, il valore predefinito per il numero massimo di processi aziendali attivati è 10. È possibile specificare un valore diverso utilizzando la colonna Organization.MaximumActiveBusinessProcessFlowsAllowedPerEntity. Tuttavia, se il valore è maggiore di 10, è possibile notare una diminuzione nelle prestazioni del sistema quando si cambiano processi o si apre una riga con un processo aziendale assegnato. Questo problema diventa più rilevante se i processi si estendono su più tabelle.

Le impostazioni seguenti non sono personalizzabili:

  • Il numero massimo di fasi per tabella nel processo è 30.

  • Il numero massimo di procedure in ogni fase è 30.

  • Il numero massimo di tabelle che possono partecipare al flusso di processo è 5.

Note

Puoi indicarci le tue preferenze di lingua per la documentazione? Partecipa a un breve sondaggio. (il sondaggio è in inglese)

Il sondaggio richiederà circa sette minuti. Non viene raccolto alcun dato personale (Informativa sulla privacy).

  • Last updated on