Gestion des champs personnalisés

Les champs personnalisés permettent de créer des champs pour vos fiches.
Ce document traite de la manipulation des champs personnalisés via l'API.
Il faut noter que l'API propose des options non accessibles sur l'interface graphique.

Créer son premier champ personnalisé

Les champs personnalisés sont décrits dans des fiches de type field_characteristics.

Le script suivant crée un champ personnalisé Disponibilité.

Code

#! /usr/bin/env python3

# remplacez la valeur exemple ci-dessous par celle de votre token
TOKEN = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0ZW5hbnRJZCI6ImRlZmF1bHQiLCJpc3MiOiJhdXRoMCIsImFjdGlvbiI6W10sImV4cCI6MzMyNzI3NjYwMzgsImxvZ2luIjoiYXBpIn0.wEwtFt7QkTbda7qajHiVW5rydAbKMWMOYfrju9pvS6w'

# remplacez la valeur exemple ci-dessous par celle de votre tenant
TENANT = 'default'

# remplacez la valeur exemple ci-dessous par celle de votre host
HOST = 'http://localhost:1080'

#############################################################################
import requests
import sys

# mimetype utilisé pour formater une application
mimetype = "application/vnd.cartosi.card+json;version=0.3"

headers = {
    "Authorization": 'Bearer {"token":"%s","myTenant":{"id":"%s"}}' % (TOKEN, TENANT),
    "Accept": mimetype,
    "Content-Type": mimetype
}

custom_field = {
    "id": "123-disponibility",
    "label": "Disponibilité",
    "code": "meta_disponibility",
    "standard": False,
    "used_by": ["application"],
    "visible": True,
    "description": "Niveau de disponibilité de l'application",
    "type": "text",
    "mandatory": "optional",
    "unique": False,
    "multiple_values": False,
    "access_nature": ["create", "read", "update", "delete"]
}

rep = requests.put(HOST + "/api/v2/field_characteristics/" + custom_field["id"], json=custom_field, headers=headers)

# en cas d'erreur ...
if rep.status_code != 200:
    print("Erreur %d : %s" % (rep.status_code, rep.text))
    sys.exit(1)

La description de chaque champ est disponible sur field_characteristics.

L'image suivante montre le champ disponibilité dans l'interface graphique.

Affichage du champ Disponibilité dans l'interface graphique

Les attributs notoires des champs personnalisés

`code`

Le code correspond au nom du champ dans les JSON. Par exemple, si on remplace le code meta_disponibility par _disponibilite, le JSON de l'application Data Lake, changera de :

Code

{
    "cartoVersion": "4.1.14",
    "icon": "fas fa-cubes",
    "id": "b69161f4-d0d5-0458-bde9-31e2ed7a2da1",
    "it_departments": [
        "62851c3b-d3ef-623f-6b85-5ef70b694b21"
    ],
    "label": "Data lake",
    "maj_date": "2018-12-17T19:31:14+00:00",
    "meta_disponibility": "90%",
    "meta_eea5a04c-5d4f-4f14-b64f-823ac59ca643": [
        "Spain"
    ],
    "teamleader": "raymond@carto-si.com"
}

à :

Code

{
    "_disponibilite": "90%",
    "cartoVersion": "4.1.14",
    "icon": "fas fa-cubes",
    "id": "b69161f4-d0d5-0458-bde9-31e2ed7a2da1",
    "it_departments": [
        "62851c3b-d3ef-623f-6b85-5ef70b694b21"
    ],
    "label": "Data lake",
    "maj_date": "2018-12-17T19:31:14+00:00",
    "meta_eea5a04c-5d4f-4f14-b64f-823ac59ca643": [
        "Spain"
    ],
    "teamleader": "raymond@carto-si.com"
}

Le champ meta_disponibility a été remplacé par _disponibilite.

`access_nature`

Permets de savoir si la valeur d'un champ peut être lue, créée, modifiée ou effacée. Sauf cas particulier, devrait toujours être ["create", "read", "update", "delete"].

`mandatory`

Est-ce que le champ est obligatoire ? Ce "booléen" à trois états permet de rendre obligatoire le champ de deux manières :

refuser une fiche qui n'a pas de valeur dans ce champ
accepter une fiche avec le champ vide, mais créer des alertes indiquant que la valeur est vide (en cours d'implémentation)

`multiple_values`

Permets d'indiquer si le champ accepte une seule valeur ou un tableau de valeur.

`type`

La liste des types de champs indique la liste des types disponibles. Attention à deux choses :

seuls les types utilisables avec les champs personnalisés peuvent être sélectionnés
l'interface graphique ne sait pas afficher certains types de champs lorsque multiple_values est vrai.

La sélection des types disponibles est beaucoup plus grande via les API que via l'interface graphique.

`used_by`

Indique les types de fiches pouvant utiliser le champ personnalisé.
Comme pour type, l'API offre un plus grand choix que celui disponible dans l'interface graphique.

`visible`

Si faux, la donnée n'est pas affichée par l'interface graphique.

Last modified on November 25, 2025