Per: Amministratori
Eseguire un'importazione con una chiave di gestione
Crea un'importazione, carica un file CSV e allegalo, quindi controlla ogni riga e riprova con quelle che hanno dato errore.
In questo articolo9 sezioni
Prima di iniziare
Questa pagina spiega come eseguire un’importazione utilizzando una chiave di gestione. Le procedure per effettuare le importazioni sono simili a quelle descritte in Integration › Imports. Tutti i percorsi utilizzati per l’importazione rientrano nella sezione https://prd-api-manage.caseactive.com/v1/integration/<hub id>. Per informazioni sulle colonne presenti nei file importati, si veda Indica le colonne necessarie per ciascuna importazione.
Chiamate
| Chiamata | Cosa fa |
|---|---|
POST /imports | Viene creato un import. |
GET /drive/private?import_id=<id>&media_group=docs&media_extension=csv | Fornisce un indirizzo per caricare il proprio file. |
PUT /imports/<import_id> | Si attiva il file caricato, in modo che l’importazione possa iniziare. |
GET /imports | Elenca le tue importazioni, in ordine di data di importazione più recente. Viene indicato anche il livello di avanzamento di ciascuna importazione. |
GET /imports/<import_id> | Elenca le righe relative all’importazione. |
PUT /imports/<import_id>/<unique_id> | Riprova per una riga che è fallita. |
1. Crea l'importazione
| Campo | Cosa fa | Necessario |
|---|---|---|
name | Un nome per esso: lettere, numeri, spazi e segni di punteggiatura. | Sì. |
source | Ciò che lo ha causato… ad esempio, claims-sync. Questo elemento viene indicato come “fonte” nel Pannello di Controllo. | Sì. |
type | Uno dei tipi elencati di seguito | Sì. |
type | Sullo schermo |
|---|---|
post_user | Aggiungere utenti |
put_user | Modificare gli utenti |
post_case | Creare casi/circostanze. |
put_case | Modificare i casi |
post_case_permission | Assegnare utenti ai casi |
delete_case_permission | Eliminare gli utenti assegnati alle singole casi. |
post_case_post | Creare post di tipo “case”. |
curl -X POST https://prd-api-manage.caseactive.com/v1/integration/ca-7e6d5c4b3a2f10/imports \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "October claimants", "source": "claims-sync", "type": "post_user"}'
Risponde a 201 con import_id, come ad esempio import::20261002141503_3f9a1c2b7d4e60.
2. Carica il file
Chiedere un indirizzo di caricamento. GET /drive/private?import_id=<import_id>&media_group=docs&media_extension=csv. Risponde a una domanda. url E un insieme di… fields. Inviate il file lì, come se fosse un semplice file normale. multipart/form-data POST: per ogni istanza che viene generata. fields Esattamente come indicato, e il file è l’ultimo in lista. file:
curl -X POST "<url>" \
--form-string "key=<fields.key>" \
--form-string "<every other entry of fields, as given>" \
-F "file=@october-claimants.csv"
- Invia gli elementi di
fieldsinsieme a--form-string, non a-F. Alcuni di questi elementi iniziano con<, mentre altri contengono;.-Finterpreta questi elementi come file o opzioni. - L’indirizzo funziona per un’ora.
- Salva il file in formato CSV, utilizzando il codice di trasmissione UTF-8. I nomi delle colonne devono essere indicati nella prima riga del file.
- Un file può contenere fino a 25.000 righe, sotto i nomi delle colonne. Un file più lungo non può essere importato correttamente; quindi è necessario dividere il file in file di almeno 25.000 righe ciascuno, e importare ogni file separatamente.
- Tenere
fields.key: è il modo in cui si collega il file in seguito.
3. Allega il file
PUT /imports/<import_id> L’importazione inizia con la chiave di caricamento. Questo è sufficiente per far funzionare il processo di importazione. 204.
{"media_key": "<fields.key>"}
Associare un file una volta sola. Se l’importazione fallisce, correggere il file e riprovare l’importazione.
4. Verificare i progressi
GET /imports elenca le importazioni del sistema, in ordine di data di creazione. Per ogni importazione, vengono indicati i valori di status, total, passed e failed.
QUEUED: È stato creato, oppure è stato associato, ma non è ancora stato letto.PROCESSED: Il file è stato letto e memorizzato.totalLe righe si muovono una alla volta. È completato quando…passedE…failedFanno insieme un totale ditotal.FAILED: Il file non è stato in grado di essere letto; non contiene righe, oppure il numero di righe è superiore a 25. L’importazione avviene tramite uno dei seguenti metodi:error_msg,ImportFileUnreadableException,ImportFileEmptyExceptionoImportFileTooLargeException.
Le righe vengono importate nel hub ogni due importazioni consecutive; quindi, un file di grandi dimensioni richiederà del tempo per essere importato. Gli amministratori e i manager del tuo hub ricevono email quando un’importazione fallisce o quando la prima riga dell’file non viene importata correttamente.
GET /imports/<import_id> elenca le righe che sono state eseguite, nell’ordine in cui si trovano nel file. Ogni riga può contenere fino a 1000 elementi. I valori rappresentati da limit e start_key sono quindi i nomi degli elementi presenti nella riga corrispondente.
{
"data": {
"items": [
{
"unique_id": "unique::20261002141503_3f9a1c2b7d4e60_0000002",
"line": 2,
"type": "post_user",
"status": "SUCCEEDED",
"data": {"username": "jane.sample@example.com", "given_name": "Jane", "family_name": "Sample", "host_ref_id": "cl-1042"},
"output": {"host_id": "ca-7e6d5c4b3a2f10", "user_id": "cu-4f1c2a9e8b7d60"}
}
],
"currentItemCount": 1,
"selfLink": "https://prd-api-manage.caseactive.com/v1/integration/ca-7e6d5c4b3a2f10/imports/import::20261002141503_3f9a1c2b7d4e60"
}
}
| Campo | Cosa contiene |
|---|---|
line | Il numero della riga nel tuo file, come fanno le fogliate per contare le righe; i nomi delle colonne corrispondono alla prima riga. |
data | Le celle della riga, così come inviate… |
status | SUCCEEDED, FAILED o QUEUED… mentre si attende un tentativo di riprova. |
output | Quello che fa: l’user_id, l’case_id, o entrambi, per una riga che mette qualcuno in una determinata situazione. |
schema_errors | Per una cella che non ha superato il controllo: la colonna in questione, e quali sono i problemi presenti. |
error_msg | Perché il tentativo di eseguire l’operazione è fallito… In altre parole, perché quel comando rappresenta un errore. Esempi di tali errori sono CaseReferenceIdExistsException. |
Una riga viene considerata “completata” soltanto quando il suo cambiamento è avvenuto correttamente. Una riga la cui identificazione, riferimento o nome coincidono con quello di un altro record fallisce l’operazione di modifica. In tal caso, il nome del record che non può essere modificato viene visualizzato come “rifiutato”. error_msg. È impossibile assegnare utenti a dei casi o creare nuove righe di post per i casi chiusi. {"_schema": ["Case is closed"]} in schema_errors: È necessario riaprire il caso, per poi importare nuovamente quella riga.
Il valore di unique_id rappresenta l’ID dell’elemento importato, insieme al numero di riga in cui si trova quell’elemento nel file. Quindi, il valore di import::20261002141503_3f9a1c2b7d4e60 corrisponde a unique::20261002141503_3f9a1c2b7d4e60_0000002.
5. Riprova una riga
PUT /imports/<import_id>/<unique_id> con {"retry": true} Si verifica di nuovo un errore nella esecuzione del programma, proprio come prima, alla fine del turno di esecuzione del tuo hub. Il programma restituisce un risultato negativo. 204, E l’importazione… failed Si procede a contare i “drops”, uno alla volta, fino a quando non si esaurisce il numero di righe disponibili. Questo metodo può essere utilizzato per le righe che hanno fallito per motivi legati al tempo o ad altre circostanze. Se una riga presenta errori, è necessario correggere il file e iniziare un nuovo processo di importazione.
Cosa succederà dopo?
Le righe relative agli importi fanno esattamente ciò che le stesse righe fanno sullo schermo: le persone aggiunte non vengono inviate via email; le persone che vengono inserite nelle “case” con l’invito ricevono automaticamente l’invito. Le nuove “case” vengono gestite secondo le regole definite dalle tue istruzioni per la gestione delle “case”. Inoltre, le nuove notifiche informano le persone coinvolte nella situazione. L’importazione viene registrata nel sistema di gestione delle “case” del tuo hub. Assistente virtualAssistente virtuale Un membro automatizzato del team che pubblica messaggi di benvenuto, check-in e post di aggiornamento per l'azienda; i suoi post sono contrassegnati da un badge di Assistente Virtuale.Inviare lo stesso file due volte significa che ogni riga viene inviata di nuovo. Le righe che incontrano problemi durante il primo invio falliscono, e i post vengono inviati due volte. Per risolvere i problemi legati alle righe che non vengono inviate correttamente, si veda… Determinare quali righe dell’importazione devono essere ignorate..
Se una chiamata viene rifiutata
| Stato | message | Perché |
|---|---|---|
| 400 | SchemaFieldsException | Il campo è mancante o non valido. Ad esempio, un name contenente altri caratteri, oppure un media_key in cui non è stato caricato alcun contenuto. |
| 403 | ImportFileAlreadyAttachedException | L’importazione ha già il proprio file, oppure è già stato letto: si può quindi iniziare una nuova operazione di importazione. |
| 403 | BotNotAllowedException | Hai utilizzato /v1/<hub id>/imports invece di /v1/integration/<hub id>/imports. |
| 404 | ItemNotFoundException | Non importa, né è necessario inserire quel ID nel proprio hub. |