Applicazioni

Application Knowledge copia i contenuti esterni selezionati in Ciele come Sources ricercabili. Ogni Source segue il normale percorso di ingestion, compare nelle citazioni e risponde solo per gli Assistants collegati. L'integrazione è diretta. Non utilizza Merge né altri broker di integrazione.

Connessione, importazione e origine

Un Application Connection memorizza un account esterno autorizzato. Un Application Import seleziona i contenuti all'interno di quell'account, una pianificazione e gli Assistenti autorizzati a effettuare ricerche su di essi. Una sincronizzazione crea o aggiorna una Ciele Source per ogni elemento remoto.

Utilizza una sola Connection per più Import quando il loro ambito o i link agli Assistenti sono diversi. Ad esempio, una singola Slack Connection può fornire set di canali distinti ad Assistenti diversi.

Le connessioni Salesforce, ServiceNow e Slack appartengono all'Organization. Ogni Organization può avere una Connection per ciascuno di questi provider. Le connessioni a OneDrive e Google Drive appartengono al Member che le autorizza. Ogni Member può collegare un account per ciascun provider personale.

Un Organization Admin può visualizzare i metadati di una Connection personale e rimuovere una Connection personale. Solo il Member proprietario può riconnetterla. Le credenziali del provider non superano mai il perimetro del Member. Le Imported Sources costituiscono la conoscenza dell'organizzazione e seguono i link degli Assistenti configurati.

Collega un account

Un Organization Admin o un Owner può connettere Salesforce, ServiceNow o Slack. Un Member con l'autorizzazione Knowledge edit può connettere il proprio OneDrive o Google Drive e gestire gli Import.

1. Apri Library e seleziona Applications, oppure apri Knowledge di un Assistente e seleziona Applications.
2. Seleziona Connect sul provider.
3. Per Salesforce o ServiceNow, inserisci un Connection name, l'instance URL, il client ID e il client secret.
4. Per Slack, OneDrive o Google Drive, seleziona Continue connecting nella pagina di connessione di Ciele.
5. Accedi al sito web del provider e approva l'accesso. Ciele aggiorna quindi l'elenco Applications.
6. Crea un Import, seleziona il suo scope e collega almeno un Assistant.
7. Scegli la sincronizzazione Daily o Manual.
8. Salva l'Import e attendi che le sue Sources diventino Ready.
9. Prova una risposta e apri la relativa citazione della Source denominata.

Slack, OneDrive e Google Drive ti chiedono di accedere e di autorizzare l'accesso. I membri non inseriscono un OAuth client ID né un OAuth client secret. Il deployment di Ciele fornisce tali credenziali. Not now chiude la finestra di connessione senza collegare un account.

L'editor dell'Assistente mostra le Importazioni dell'organizzazione che puoi collegare. La Library è la vista completa dell'Organization e include ogni Import.

Ambiti del provider

Ciele segnala i file non supportati, gli elementi vuoti e le esclusioni specifiche del provider come elementi ignorati. Un elemento non valido non interrompe l'elaborazione dei contenuti validi nello stesso ciclo di esecuzione.

Sincronizzazione e stato

Seleziona Sync now per un'esecuzione immediata. Pause interrompe le esecuzioni pianificate senza eliminare le Sources. Resume accoda una nuova esecuzione. La modifica di uno scope reimposta il relativo checkpoint e pianifica un aggiornamento completo della nuova selezione.

La tabella Configured imports mostra una riga per ogni Import. La riga mostra lo stato, l'ultima e la prossima sincronizzazione, il numero di Documenti e i totali degli elementi aggiornati e di quelli non riusciti dell'ultima esecuzione. Tieni il puntatore sui totali per visualizzare i conteggi di elementi rilevati, rimossi e ignorati. Gli errori di autorizzazione del provider contrassegnano la Connection per la riconnessione e creano un Alert. Un'esecuzione successiva andata a buon fine elimina l'Alert.

Seleziona un Import o il relativo numero di Documents per visualizzare tutti gli elementi che sono stati importati. Seleziona un elemento per aprire il relativo Document con le schede Memories, Content e Chunks e il relativo riepilogo. Per un elemento che Ciele non ha ancora elaborato, si apre invece la sua pagina Source.

Mentre è in corso una sincronizzazione, la console mostra una scheda attività nell'angolo in basso a destra. La scheda mostra il numero di elementi completati e il totale, ad esempio 261/291. Seleziona la freccia per visualizzare fino a quattro elementi con il relativo stato. Gli elementi che hanno riportato un errore vengono mostrati per primi.

L'identità remota rimane stabile. Un elemento remoto modificato aggiorna la Source esistente, quindi i link e le citazioni non cambiano. Un elemento remoto rimosso elimina la sua Source attiva, ma conserva un tombstone interno, che consente, in caso di successiva riapparizione, di creare la sostituzione corretta senza duplicarla.

I limiti di frequenza del provider utilizzano il valore di ritardo per i tentativi successivi restituito. Anche le importazioni giornaliere vengono eseguite secondo il normale programma dei worker di Ciele, quindi il processo web non deve rimanere aperto.

Rispondi alle menzioni su Slack

Le importazioni da Slack e le risposte conversazionali sono funzionalità distinte. Le importazioni copiano la knowledge in Ciele. Le risposte conversazionali eseguono un Assistente pubblicato quando qualcuno menziona @Ciele in un canale abilitato.

1. Chiedi al tuo amministratore del deployment di configurare la Slack Events API descritta di seguito.
2. Apri la connessione Slack in Applications e seleziona Slack assistant.
3. Seleziona Authorize conversational permissions e approva l'accesso in Slack. Le Import Connections non possono pubblicare finché non completi questo passaggio.
4. Seleziona un Assistant pubblicato dalla tua Organization.
5. Invita Ciele in ogni canale, quindi seleziona il Channels consentito dall'elenco. Non puoi selezionare i canali a cui Ciele non ha aderito e i canali Slack Connect.
6. Seleziona Save Slack assistant.
7. Menziona @Ciele con una domanda. Ciele risponde nel thread di quel messaggio.

L'Assistente utilizza la propria knowledge collegata, la configurazione pubblicata e il contesto Slack recente. Legge fino a 15 messaggi del canale e 15 messaggi del thread precedenti alla menzione. I limiti di frequenza di Slack possono ridurre tale contesto. Ciele non legge l'intero workspace per ogni risposta. Ciele considera la trascrizione del canale come materiale di riferimento non attendibile, non come istruzioni. Ogni persona in un thread ha la propria conversazione Ciele. Quella conversazione prosegue nelle loro successive menzioni nel thread. I messaggi diretti non attivano questa funzionalità.

Ogni workspace e canale Slack deve essere associato a una singola connessione abilitata a un'Organization Ciele. Quando due organizzazioni abilitano lo stesso canale, Ciele non risponde in quel contesto. Ciele genera un Alert in entrambe le Organizzazioni finché una di esse non rimuove il canale. La riconnessione a un altro workspace o a un'altra applicazione Slack azzera la configurazione delle conversazioni. La connessione Slack deve appartenere alla stessa applicazione Slack di SLACK_APPLICATION_APP_ID del deployment. In caso contrario, Ciele rifiuta di salvare le impostazioni.

Configura l'API Slack Events

Esegui il deploy della migrazione del database di Slack prima di abilitare gli eventi. Configura questi valori validi solo per il server dalla pagina Basic Information di Slack:

SLACK_APPLICATION_APP_ID=
SLACK_SIGNING_SECRET=

Mantieni l'OAuth client ID, il client secret e l'HTTPS OAuth callback esistenti. Il signing secret è diverso dal client secret. Non inserire mai nessuno dei due segreti in una variabile di ambiente pubblica.

1. Aggiungi app_mentions:read e chat:write sotto OAuth & Permissions, oltre agli ambiti di importazione esistenti.
2. Abilita Event Subscriptions e imposta l'URL della richiesta su {origin}/api/slack/events.
3. Iscriviti all'evento bot app_mention e salva la configurazione.
4. Configura un provider di modelli dell'organizzazione in grado di gestire il traffico degli assistenti pubblicati.

Ciele richiede i due ambiti di risposta solo quando un Member seleziona Authorize conversational permissions. Una Connection utilizzata esclusivamente per gli Import mantiene un token di sola lettura.

L'endpoint verifica le firme di Slack e memorizza ogni evento prima di confermarne la ricezione. Il worker viene eseguito dopo la conferma e utilizza lo stesso runtime di conversazione degli Assistenti pubblicati. Gli abbonamenti ai provider personali non gestiscono il traffico Slack.

Il deployment espone anche /api/cron/run-slack, protetto da CRON_SECRET, per i tentativi di ripetizione in coda e per i worker interrotti. Lo scheduler self-hosted lo esegue ogni 5 minuti. La pianificazione Vercel fornita viene eseguita quotidianamente, poiché il piano Hobby consente solo pianificazioni giornaliere. Configura uno scheduler autenticato con esecuzione frequente quando una distribuzione ospitata richiede un rapido ripristino tramite tentativi ripetuti.

Ciele crea un Alert quando non riesce a rispondere a una menzione. Tra le possibili cause figurano un canale a cui Ciele non ha aderito, un canale archiviato o condiviso, un Assistente non pubblicato e una consegna non riuscita. Se l'esito della consegna su Slack è incerto, Ciele disattiva i repost automatici e crea un Alert. Controlla il thread di Slack prima di riprovare manualmente un evento interessato. Quando il token di Slack viene revocato o scade, Ciele contrassegna la Connection per la riconnessione. L'elenco Applications mostra quindi Reconnect.

Riconnetti o elimina

Seleziona Reconnect quando il consenso scade o l'account cambia. La Connection mantiene la stessa identità e i suoi Import rimangono configurati.

L'eliminazione di un Import elimina le sue Sources sincronizzate per ogni Assistant collegato. L'eliminazione di una Connection comporta l'eliminazione di tutti i relativi Import e Source. La conferma mostra il numero di Import, Source e collegamenti all'Assistente interessati. Ciele tenta la revoca del token del provider quando quest'ultimo la supporta, quindi rimuove sempre le credenziali locali.

Configura OAuth per un'implementazione self-hosted

Imposta APP_ENCRYPTION_KEY prima di connettere qualsiasi provider. Ciele sigilla con quella chiave i token OAuth e i client secret di Salesforce e ServiceNow per ogni Connessione.

Il servizio gestito Ciele fornisce le registrazioni OAuth condivise per Slack, Microsoft e Google. Ogni implementazione self-hosted fornisce le proprie registrazioni tramite variabili di ambiente. Queste registrazioni identificano il deployment di Ciele. Non identificano un account Organization o Member.

Crea le applicazioni OAuth del provider e imposta le coppie che abiliti:

SLACK_APPLICATION_CLIENT_ID=
SLACK_APPLICATION_CLIENT_SECRET=
MICROSOFT_APPLICATION_CLIENT_ID=
MICROSOFT_APPLICATION_CLIENT_SECRET=
GOOGLE_APPLICATION_CLIENT_ID=
GOOGLE_APPLICATION_CLIENT_SECRET=
APPLICATION_IMPORT_MAX_REMOTE_ITEMS=100000
APPLICATION_IMPORT_MAX_ORG_BYTES=5368709120
APPLICATION_IMPORT_MAX_CONCURRENT=3

I tre limiti riguardano gli elementi remoti sincronizzati per Connection, i byte dell'Application memorizzati per Organization e i claim di sincronizzazione attivi per Organization. Riduci questi valori per le implementazioni di dimensioni minori. Ciele esegue il checkpoint del cursore del provider e prosegue gli import di grandi dimensioni in successivi durable claim.

Le credenziali client di Salesforce e ServiceNow sono specifiche per l'Organization connessa. L'amministratore li inserisce nel modulo protetto Connection. Ciele le sigilla prima dell'archiviazione e non le restituisce mai al browser. ServiceNow utilizza l'Authorization Code e non memorizza né username né password.

Registra un unico URL di callback esatto per ogni provider. Sostituisci {origin} con l'origine HTTPS pubblica della tua console Ciele:

La mancanza di una coppia di variabili di ambiente per Slack, Microsoft o Google impedisce l'autorizzazione per quel provider. Connect apre comunque la pagina di connessione di Ciele, che spiega che la distribuzione richiede la configurazione. Gli utenti con ruolo Admin e Owner possono aprire la guida alla configurazione da quella pagina. Salesforce e ServiceNow rimangono disponibili perché l'Admin inserisce la propria registrazione OAuth nel modulo Connection. Entrambi utilizzano l'Authorization Code. Anche Salesforce, Microsoft e Google utilizzano PKCE. Ogni transazione ha una durata breve ed è vincolata all'Organization, al Member che l'ha avviata, al provider e all'esatto callback URL.

Risoluzione dei problemi

Le Importazioni di applicazioni sono di sola lettura per i contenuti di origine, e il token di una Connessione di importazione non può effettuare post. Solo una Connection con le autorizzazioni per le conversazioni completate può pubblicare risposte su Slack. Ciele non applica gli elenchi di controllo degli accessi dei provider al momento della risposta né supporta le librerie di SharePoint.