Un CUID (Collision-resistant Unique Identifier) est une chaîne alphanumérique de 16 caractères utilisée pour identifier les ressources sur toute la plateforme ActivityInfo. Ces identifiants sont essentiels pour l'utilisation dans les formules, l'API d'ActivityInfo et le package R, car ils restent constants même si le nom d'affichage d'une ressource est modifié.
Caractéristiques clés
- Format : Les CUID sont composés de 16 caractères utilisant des lettres minuscules (a-z) et des chiffres (0-9).
- Structure : Chaque CUID doit commencer par une lettre (par exemple, cw0qkvfkq6jnlx3r).
- Permanence : Contrairement aux étiquettes ou aux noms, un CUID est immuable une fois attribué à une ressource.
Hiérarchie et portée de l'unicité
Les CUID sont générés sur la base d'une hiérarchie spécifique. Leur unicité est soit globale sur l'ensemble d'un serveur, soit limitée à un « contenant » parent.
1. ID Uniques au niveau global
Les ressources suivantes se voient attribuer des CUID qui sont uniques sur un même serveur ActivityInfo :
- Bases de données : Le contenant de plus haut niveau pour tous les formulaires et données.
- Formulaires : Formulaires standards utilisés pour la collecte de données.
- Rapports : Résultats analytiques comme les tableaux croisés dynamiques ou les tableaux de bord.
2. ID à portée limitée au contenant
Certaines ressources ne requièrent l'unicité qu'au sein de leur contenant parent immédiat. Cela signifie que le même CUID peut potentiellement exister à différents endroits sur le même serveur sans conflit :
- Champs : Uniques uniquement au sein de leur Formulaire spécifique. Deux formulaires différents peuvent avoir des champs avec des CUID identiques.
- Options de sélection : Les options dans les champs de Sélection unique ou de Sélection multiple sont Uniques uniquement au sein de leur Champ spécifique.
- Enregistrements : Uniques uniquement au sein de leur Formulaire spécifique. Un ID d'enregistrement dans le « Formulaire A » peut être identique à un ID d'enregistrement dans le « Formulaire B ».
- Dossiers : Contenants structurels utilisés pour organiser les formulaires. Le CUID d'un formulaire n'est unique qu'au sein d'une base de données. Deux dossiers différents peuvent avoir des CUID identiques dans des bases de données différentes.
Applications pratiques
API et Intégrations
Lors de l'utilisation de l'API pour interroger des données ou mettre à jour des schémas, les CUID sont le principal moyen de cibler les ressources. Par exemple, pour récupérer des enregistrements d'un formulaire spécifique, vous devez fournir le CUID de ce formulaire (formId) à get form records.
Formules
Les CUID sont utilisés dans les formules pour faire référence à des champs ou des formulaires spécifiques, garantissant que la formule ne se brise pas si un champ est renommé.
Package R
Le package R d'ActivityInfo utilise les CUID pour presque toutes les fonctions afin de référencer des ressources spécifiques lors de la récupération de schémas, de l'interrogation de données et de l'exécution d'opérations sur les enregistrements telles que l'ajout, la modification et la suppression.
Trouver les CUID
- Package R d'ActivityInfo : Vous pouvez utiliser la fonction getDatabaseTree pour lister les ressources disponibles et leurs CUID.
- API d'ActivityInfo : Vous pouvez obtenir une liste de ressources (dossiers, formulaires et sous-formulaires) et leurs CUID dans une base de données.
- Dans le navigateur : Les CUID sont souvent visibles dans l'URL lorsque vous consultez une base de données ou un formulaire spécifique dans l'interface web d'ActivityInfo. Dans l'exemple ci-dessous, le CUID du formulaire Beneficiary Registry est visible dans la barre d'adresse.
- CUID des enregistrements : Vous pouvez voir le CUID d'un enregistrement dans un formulaire ou un sous-formulaire dans le Tableau Interactif en cliquant sur « Vues », puis sur « Sélectionner des colonnes ».
Cochez l'option « ID de l'enregistrement » sous « Colonnes disponibles » pour afficher les CUID des enregistrements.
- CUID des champs : Vous pouvez voir les CUID des champs d'un formulaire en ouvrant le formulaire, en cliquant sur « Paramètres du formulaire » dans le coin supérieur droit de l'écran, puis en sélectionnant « Exporter les champs ».
Cela téléchargera un fichier CSV affichant tous les CUID des champs du formulaire.
Générer des CUID
Lorsque vous soumettez une requête via l'API d'ActivityInfo pour ajouter une nouvelle base de données, un nouveau dossier, un nouveau formulaire, etc., vous devrez générer l'ID de la nouvelle ressource.
Le projet Collision-resistant ids (CUID2) dispose de bibliothèques dans plusieurs langages de programmation pour générer des ID qui seront acceptés par ActivityInfo.