The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: Flussi di lavoro
description: Distribuisci workflow preconfigurati con la tua app.
---
import { PageBanner } from "/snippets/page-banner.mdx"
## Definisci un workflow
Le app possono includere workflow. Ogni chiamata a `defineWorkflow()` descrive un workflow: un trigger e i passaggi che esegue. Al momento dell'installazione, Twenty lo crea come workflow attivo nello spazio di lavoro, pronto per essere eseguito.
Questo workflow viene eseguito quando viene creata un'azienda. Chiama una delle funzioni logiche dell'app, quindi scrive il risultato nell'azienda:
```ts src/workflows/score-new-companies.ts
import {
defineWorkflow,
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';
const COMPANY = STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier;
const SCORE_COMPANY_FUNCTION = '0f6c0b3e-8a4f-4f0e-9d0a-3c1e5b7a2d41';
const SCORE_NEW_COMPANIES = {
workflow: 'c2a4e6f8-1b3d-4f5a-8c7e-9d0b2a4c6e81',
trigger: 'c2a4e6f8-1b3d-4f5a-8c7e-9d0b2a4c6e82',
score: 'c2a4e6f8-1b3d-4f5a-8c7e-9d0b2a4c6e83',
save: 'c2a4e6f8-1b3d-4f5a-8c7e-9d0b2a4c6e84',
};
export default defineWorkflow({
universalIdentifier: SCORE_NEW_COMPANIES.workflow,
name: 'Score new companies',
version: {
trigger: {
universalIdentifier: SCORE_NEW_COMPANIES.trigger,
type: 'DATABASE_EVENT',
settings: {
objectUniversalIdentifier: COMPANY,
action: 'created',
},
nextStepIds: [SCORE_NEW_COMPANIES.score],
},
steps: [
{
universalIdentifier: SCORE_NEW_COMPANIES.score,
name: 'Score the company',
type: 'LOGIC_FUNCTION',
logicFunctionUniversalIdentifier: SCORE_COMPANY_FUNCTION,
input: { companyName: '{{trigger.properties.after.name}}' },
nextStepIds: [SCORE_NEW_COMPANIES.save],
},
{
universalIdentifier: SCORE_NEW_COMPANIES.save,
name: 'Save the score',
type: 'UPDATE_RECORD',
input: {
objectUniversalIdentifier: COMPANY,
objectRecordId: '{{trigger.recordId}}',
objectRecord: { leadScore: `{{${SCORE_NEW_COMPANIES.score}.score}}` },
fieldsToUpdate: ['leadScore'],
},
nextStepIds: [],
},
],
},
});
```
Punti chiave:
* Il flusso di lavoro e ogni passaggio necessitano del proprio `universalIdentifier`, e il trigger può averne uno. Mantienili stabili tra le release: è così che Twenty trova una corrispondenza con il workflow installato all'installazione successiva.
* `nextStepIds` collega il grafo. Il trigger punta ai primi passaggi e ogni passaggio punta ai passaggi eseguiti dopo di esso.
* Un passaggio legge l'output precedente con `{{trigger.\<path>}}` o `{{\<step universalIdentifier>.\<path>}}`.
* La build convalida l'intera definizione: tipi di trigger o passaggio non supportati, collegamenti tra passaggi non validi e riferimenti a passaggi sconosciuti causano l'errore.
* `isSystem` (facoltativo, il valore predefinito è `false`) nasconde il workflow dagli elenchi che escludono i workflow di sistema. Modifica solo ciò che viene visualizzato.
## Riferimento ad altre entità
I passaggi e i trigger puntano ai metadati tramite identificatore universale, mai tramite nome o id:
* **Oggetti e campi**: quelli dell'app oppure quelli standard tramite `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`. L'esempio precedente presuppone che l'app definisca anche un campo numerico `leadScore` su Company con [`defineField()`](/it/developers/extend/apps/data/extending-objects): un passaggio relativo a un record che scrive un campo assente dallo spazio di lavoro causa l'errore di installazione.
* **Funzioni logiche**: quelle dell'app, esposte come [azione del workflow](/it/developers/extend/apps/logic/logic-functions#exposing-a-function-as-an-ai-tool-or-workflow-action) con `workflowActionTriggerSettings`. L'applicazione Custom dello spazio di lavoro può anche fare riferimento alle azioni dei workflow delle altre app installate nello spazio di lavoro, come possono fare i workflow creati nell'app.
* **Agenti**: quelli dell'app, da [`defineAgent()`](/it/developers/extend/apps/logic/skills-and-agents).
Un riferimento che Twenty non riesce a risolvere causa l'errore di installazione.
## Trigger
| Tipo | Viene eseguito quando | Impostazioni |
| ---------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MANUAL` | Un utente lo avvia | `availability` (facoltativo): `GLOBAL`, oppure `SINGLE_RECORD` / `BULK_RECORDS` con un `objectUniversalIdentifier`. Aggiunge una voce al menu dei comandi, con `icon` e `isPinned` facoltativi. |
| `CRON` | In base a una pianificazione | `type`: `DAYS`, `HOURS` o `MINUTES` con una `schedule`, oppure `CUSTOM` con un `pattern` cron. |
| `DATABASE_EVENT` | Un record cambia | `objectUniversalIdentifier`, `action` (`created`, `updated`, `deleted`, `upserted`), `fieldUniversalIdentifiers` facoltativi da monitorare (solo aggiornamenti e upsert) e `filter`. |
| `WEBHOOK` | Una richiesta HTTP raggiunge l'URL del workflow | `httpMethod` (`GET` o `POST`) ed `expectedBody` per `POST`. |
Un workflow manuale senza `availability` non ottiene alcuna voce nel menu dei comandi.
Ogni trigger accetta anche `name`, `position` e `outputSchema` facoltativi, che definiscono solo l'aspetto del flusso di lavoro nel builder. Senza di essi, Twenty usa un nome come `Manual trigger`, posiziona il trigger nella parte superiore dell'area di lavoro e calcola lo schema di output dalle impostazioni.
Un workflow webhook resta in ascolto su `https://\<your-twenty-domain>/webhooks/workflows/\<workspaceId>/\<workflowId>`, dove `workflowId` è l'id del workflow installato. Il corpo della richiesta è disponibile come `{{trigger.\<path>}}`.
## Passaggi
I workflow dell'applicazione supportano questi tipi di passaggio: `LOGIC_FUNCTION`, `AI_AGENT`, `HTTP_REQUEST`, `CLASSIFY`, `CREATE_RECORD`, `UPDATE_RECORD`, `UPSERT_RECORD`, `DELETE_RECORD`, `FIND_RECORDS`, `PICK_RECORD`, `FILTER`, `IF_ELSE`, `ITERATOR`, `FORM`, `DELAY`, `WAIT_FOR_EVENT`, `SEND_EMAIL`, `DRAFT_EMAIL`, `CREATE_CALENDAR_EVENT`, `SEND_CHAT_MESSAGE` e `EMPTY`.
I relativi input corrispondono ai passaggi del [generatore di workflow](/it/user-guide/workflows/capabilities/workflow-actions), con identificatori universali al posto dei nomi:
* I passaggi relativi ai record usano `objectUniversalIdentifier` anziché un nome di oggetto.
* I filtri e gli ordinamenti puntano ai campi con `fieldMetadataUniversalIdentifier`.
* Gli operandi di filtro accettano valori `ViewFilterOperand`, esportati da `twenty-sdk/define`. Gli operatori del gruppo di filtri accettano valori stringa come `'AND'` o `'OR'`.
* I campi del modulo di tipo `RECORD` denominano il proprio oggetto con `settings.objectUniversalIdentifier`. I campi di tipo `SELECT` e `MULTI_SELECT` offrono le opzioni di un campo esistente dello stesso tipo, denominato con `settings.selectedFieldUniversalIdentifier`.
* Per eseguire il tuo codice, usa un passaggio `LOGIC_FUNCTION`. Il passaggio Code del builder non è disponibile.
* I passaggi `AI_AGENT` sono di due tipi, che non puoi combinare:
* Un passaggio Generate non ha un agente. Include le proprie `instructions`, `modelId`, `modelConfiguration` e `scope` e viene eseguito una sola volta: nessuna conversazione, nessun input umano, nessuna attesa.
* Un passaggio Agent esegue uno degli agenti della tua app, denominato con `agentUniversalIdentifier`, che include le proprie istruzioni, il modello e le autorizzazioni. Solo un passaggio Agent accetta `humanInputInstructions` e `conversation`.
Entrambi i tipi accettano `prompt` e `responseFormat` del builder, nonché `workspaceMemberId` per il membro con cui conversa l'agente.
* Lo `scope` di un passaggio `AI_AGENT` accetta le autorizzazioni di un ruolo senza la relativa identità o i predicati a livello di riga: `canReadAllObjectRecords`, `objectPermissions` e `fieldPermissions` per identificatore universale, `permissionFlagUniversalIdentifiers` e così via. Limita soltanto: l'IA del passaggio non accede mai a più dati di chi esegue il workflow. Viene risolto come un ruolo i cui flag per tutti i record sono disattivati per impostazione predefinita: le azioni sugli oggetti e i flag di autorizzazione che non concede vengono negati, gli oggetti di sistema rimangono leggibili a meno che non conceda di più, e un campo che non elenca segue il relativo oggetto. Un passaggio Generate senza uno `scope` non ottiene strumenti per i dati; un passaggio Agent viene eseguito con il ruolo del relativo agente.
* I passaggi email e calendario vengono eseguiti solo se il ruolo della tua app dispone del flag di autorizzazione corrispondente: `SystemPermissionFlag.SEND_EMAIL_TOOL` per `SEND_EMAIL` e `DRAFT_EMAIL`, `SystemPermissionFlag.CREATE_CALENDAR_EVENT_TOOL` per `CREATE_CALENDAR_EVENT`. Il workspace lo concede installando l'app e il passaggio può quindi usare qualsiasi account connesso nel workspace, come un workflow creato nell'app.
* Gli ID degli account connessi sono locali a ogni spazio di lavoro, quindi non codificarne uno in modo fisso. Specifica l'account in uno dei due modi seguenti:
* `connectedAccountHandle`: l'indirizzo email dell'account, ad esempio `'[email protected]'`. Quando l'app viene sincronizzata, l'handle viene risolto in un account con quell'indirizzo condiviso con lo spazio di lavoro (ambito `WORKSPACE`) e può eseguire il passaggio. L'account privato di un membro non può essere specificato tramite handle: pull lo mantiene come proprio `connectedAccountId`. Se più account condividono l'indirizzo, ad esempio una casella di posta collegata da due membri o tramite due provider, vince quello meno recente. Se nessuno corrisponde, la sincronizzazione non riesce e indica l'handle. Questo non è `fromHandle`, che seleziona un alias da cui inviare.
* `connectedAccountId`: una variabile, ad esempio `{{trigger.properties.after.connectedAccountId}}`. I passaggi Email accettano anche un ID membro dell'area di lavoro, ad esempio `{{trigger.properties.after.assigneeId}}`, che viene risolto nel primo account di quel membro in grado di inviare.
Imposta esattamente uno dei due.
* `SEND_CHAT_MESSAGE` invia un messaggio alla posta in arrivo di un membro del workspace, impostato con `workspaceMemberId`. Anche gli ID dei membri sono locali a ciascun workspace, quindi un'app passa una variabile, ad esempio `{{trigger.properties.after.assigneeId}}`.
## Dopo l'installazione
* Il workflow è attivo non appena l'app viene installata e le relative esecuzioni vengono visualizzate insieme alle altre esecuzioni di workflow dello spazio di lavoro.
* L'installazione di una nuova versione dell'app aggiorna il workflow sul posto.
* Gli utenti non possono modificare un workflow installato. Per personalizzarne uno, lo duplicano: la copia può essere modificata da loro.
## Workflow dell'applicazione Custom dell'area di lavoro
L'applicazione Custom dell'area di lavoro possiede i workflow creati nel workflow builder e il codice ha per essi la stessa autorevolezza del builder:
* `twenty app pull` scrive ciascuno dalla relativa versione attiva, quella pubblicata per ultima dal builder. Un flusso di lavoro la cui versione attiva usa impostazioni che un file `defineWorkflow()` non può esprimere, come un passaggio Code, viene segnalato e lasciato invariato.
* Un flusso di lavoro recuperato mantiene ciò che il builder ha memorizzato: un trigger senza `universalIdentifier`, il nome del trigger nel builder, una `position` pari a `null` per un nodo che il builder non ha mai posizionato e un `outputSchema` diverso da quello calcolato. Questi campi richiedono twenty-sdk 2.53.0 o versioni successive, applicati a un server con 2.53.0 o versioni successive: le versioni precedenti li rifiutano come chiavi sconosciute.
* `twenty app apply` pubblica come il builder. Un workflow la cui definizione corrisponde alla sua versione attiva non viene modificato. Altrimenti, la versione attiva viene archiviata e la definizione diventa una nuova versione attiva, così le esecuzioni precedenti mantengono la versione con cui sono state eseguite.
* Gli utenti continuano a modificare questi workflow nel builder e il pull successivo recupera le loro modifiche.
<PageBanner illustration="card-page-workflows" />