Centre d'aideIntégrations

Pour: Administrateurs

Lancez une importation avec une clé de gestion

Créez une importation, téléchargez un fichier CSV et joignez-le, puis vérifiez chaque ligne et réessayez celles qui ont échoué.

Dans cet article9 sections

Avant de commencer

Cette page traite de la manière d’exécuter une importation en utilisant une clé de gestion. Les procédures sont identiques à celles décrites dans Integration › Imports. Toutes les voies de navigation sont répertoriées sous https://prd-api-manage.caseactive.com/v1/integration/<hub id>. Pour savoir quelles colonnes sont nécessaires pour chaque importation, veuillez consulter Regardez les colonnes requises pour chaque importation.

Appels

AppelCe que cela fait
POST /importsCrée une importation.
GET /drive/private?import_id=<id>&media_group=docs&media_extension=csvDonne une adresse à utiliser pour télécharger son fichier.
PUT /imports/<import_id>Attachez le fichier téléchargé. Cela déclenche l’opération d’importation.
GET /importsAffiche la liste de vos importations, en commençant par les plus récentes, avec des informations sur l’état d’avancement de chaque importation.
GET /imports/<import_id>Affiche les lignes relatives à l’importation.
PUT /imports/<import_id>/<unique_id>Réessai d’une ligne qui a échoué.

1. Créez l'importation

ChampCe que cela faitRequis
nameUn nom pour cela : des lettres, des chiffres, des espaces et des barres.Oui.
sourceCe qui a provoqué cela, comme claims-sync, est indiqué comme source dans le Panneau de contrôle.Oui.
typeL’un des types suivantsOui.
typeÀ l'écran
post_userAjouter des utilisateurs
put_userModifier les utilisateurs
post_caseCréer des cas
put_caseModifier les cas concernés
post_case_permissionAssociez des utilisateurs aux cas correspondants.
delete_case_permissionÉliminez les utilisateurs assignés aux cas concernés.
post_case_postCréer des posts de cas
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"}'

Il répond à 201 avec import_id, comme dans le cas de import::20261002141503_3f9a1c2b7d4e60.

2. Téléchargez le fichier

Veuillez demander une adresse d’enregistrement via GET /drive/private?import_id=<import_id>&media_group=docs&media_extension=csv. Cette adresse correspond à un url et à un ensemble de fields. Envoyez le fichier via un POST à l’adresse multipart/form-data. Chaque entrée de fields doit être entrée correctement. Le fichier doit être placé en dernier, comme indiqué par file.

curl -X POST "<url>" \
  --form-string "key=<fields.key>" \
  --form-string "<every other entry of fields, as given>" \
  -F "file=@october-claimants.csv"
  • Envoyez les entrées de fields avec --form-string, et non avec -F. Certaines entrées commencent par <, ou contiennent un ;. Le -F est interprété comme un fichier ou une option.
  • L’adresse fonctionne pendant une heure.
  • Enregistrez le fichier en format CSV UTF-8, en veillant à ce que les noms des colonnes figurent dans la première ligne du fichier.
  • Un fichier peut contenir jusqu’à 25 000 lignes, sous les noms des colonnes. Un fichier trop long ne peut pas être importé ; il ne contient donc aucune donnée. Il est donc nécessaire de diviser le fichier en plusieurs fichiers, chacun contenant au maximum 25 000 lignes. Une importation distincte doit alors être effectuée pour chaque fichier.
  • Maintenez fields.key : c’est ainsi que vous attacherez le fichier par la suite.

3. Joignez le fichier

PUT /imports/<import_id> lance l’importation à l’aide de la clé d’enregistrement de l’upload. Cela correspond à 204.

{"media_key": "<fields.key>"}

Toutefois, il suffit de télécharger le fichier une seule fois. Si l’importation échoue, corrigez le fichier et réessayez l’importation.

4. Vérifier les progrès

GET /imports liste vos importations, en ordre décroissant de date. Pour chaque importation, on trouve les valeurs status, total, passed et failed.

  • QUEUED : créé, ou attaché, mais pas encore lu.
  • PROCESSED: Le fichier a été lu et mis à disposition. total Des rangées qui se déplacent une par une. C’est terminé lorsque… passed Et… failed Somme à combiner total.
  • FAILED : Le fichier ne peut pas être lu. Il ne contient aucune ligne, ou bien il contient plus de 25 000 lignes. L’importation se fait selon le type de fichier indiqué par error_msg : ImportFileUnreadableException, ImportFileEmptyException ou ImportFileTooLargeException.

Les lignes s’enchaînent dans le hub de votre système, à intervalles réguliers. Par conséquent, un fichier de grande taille nécessite plus de temps pour être traité. Les administrateurs et les gestionnaires de votre hub reçoivent des e-mails dès qu’une importation échoue ou que la première ligne de l’importation ne fonctionne pas correctement.

GET /imports/<import_id> liste les lignes qui ont été exécutées, dans l’ordre où elles se trouvent dans le fichier. Ces lignes sont numérotées de 1 à limit (jusqu’à 1000). De plus, il y a aussi des lignes numérotées de start_key.

{
  "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"
  }
}
ChampCe qu'il contient
lineLe numéro de la ligne dans votre fichier, comme une feuille de calcul compte les lignes ; les noms des colonnes correspondent aux lignes 1.
dataLes cellules de la rangée, tels qu’elles ont été envoyées.
statusSUCCEEDED, FAILED ou QUEUED… pendant que une tentative de réparation est en attente.
outputCe qui est produit : user_id, case_id, ou les deux, pour une ligne qui fait en sorte que quelqu’un soit placé dans une situation particulière.
schema_errorsPour une cellule qui n’a pas réussi son test : la colonne concernée, et ce qui ne fonctionnait pas.
error_msgPourquoi cette erreur a-t-elle échoué, en tant que nom d’erreur, comme CaseReferenceIdExistsException ?

Une ligne ne est considérée comme réussie que si elle a pu être modifiée. Une ligne dont l’ID de tag, l’ID de référence ou la personne coïncident avec celle d’un autre enregistrement échoue. Dans ce cas, le nom de refus est affiché. error_msg. Il y a des erreurs lors de l’assignation d’utilisateurs aux cas, ou lors de la création de nouvelles lignes de post pour les cas fermés. {"_schema": ["Case is closed"]} Dans schema_errors: Ouvrez à nouveau l’affaire, puis importez à nouveau cette ligne.

Une rangée de… unique_id Il est créé à partir de l’ID de l’importation et du numéro de la ligne dans votre fichier. Donc, la deuxième ligne… import::20261002141503_3f9a1c2b7d4e60 C’est. unique::20261002141503_3f9a1c2b7d4e60_0000002.

5. Réessayez une ligne

PUT /imports/<import_id>/<unique_id> Avec {"retry": true} Cela signifie qu’une ligne échoue à nouveau, tout comme avant, au moment où le tour de votre hub arrive. Cela répond bien à la demande. 204, Et l’importation… failed Les données sont supprimées une par une, jusqu’à ce que la ligne soit terminée. Cela sert pour les lignes qui ont échoué pour une raison quelconque, comme lors d’une période de forte activité. Si une ligne contient des erreurs, elle échoue à nouveau. Corrigez le fichier et commencez une nouvelle importation.

Que se passe-t-il ensuite ?

Les lignes d’importation font ce que les mêmes lignes font à l’écran : les personnes ajoutées ne reçoivent pas d’e-mails ; celles qui sont ajoutées aux cas avec l’invitation le reçoivent directement. Les nouveaux cas sont gérés selon vos règles de gestion des cas. De plus, les nouvelles publications informent les personnes concernées par le cas. L’importation est enregistrée comme étant effectuée par votre Assistante virtuelleAssistant virtuel Un membre d'équipe automatisé qui publie des messages de bienvenue, des enregistrements et des publications pour l'entreprise ; ses publications portent un badge d'assistant virtuel.. En envoyant le même fichier deux fois, toutes les lignes sont ré-exécutées. Les lignes qui ne fonctionnent pas lors de la première exécution échouent, et les publications sont faites deux fois. Pour corriger les lignes qui échouent à l’écran, veuillez consulter la section Correction des lignes d’importation qui échouent.

Si un appel est refusé

StatutmessagePourquoi
400SchemaFieldsExceptionUn champ est manquant ou n’est pas valide. Par exemple, un name contenant d’autres caractères, ou un media_key dans lequel rien n’a été chargé.
403ImportFileAlreadyAttachedExceptionL’importation dispose déjà de son fichier, ou il a déjà été lu : il est donc possible de commencer une nouvelle importation.
403BotNotAllowedExceptionVous avez utilisé /v1/<hub id>/imports à la place de /v1/integration/<hub id>/imports.
404ItemNotFoundExceptionPas d’importance, ou pas de rang particulier pour cette ID dans votre hub.

Articles connexes

Recherchez les colonnes nécessaires à chaque importationLes colonnes CSV obligatoires et facultatives pour chaque type d'importation, avec les formats acceptés par chacune.Cas et admissionCorriger une importation comportant des lignes en échecConsultez le journal d'importation et les erreurs de lignes, réessayez les lignes qui ont échoué pour d'autres raisons, puis corrigez et téléchargez à nouveau le fichier.Cas et admission