Kantree embarque un langage de requête puissant, qui vous permet de filtrer ou rechercher des cartes, ou encore de calculer des choses à partir d’elles.
Vous pouvez utiliser ce langage dans de multiples occasions:
- dans un workspace, filtrer ou rechercher des cartes
- chercher des cartes au niveau global
- dans un dashboard (workspace ou global), calculer des valeurs à partir de champs de cartes
- dans une carte, calculer des valeurs à partir de données inclues dans les autres champs de la carte, via un champ formule.
Filtrer les cartes
Pour rechercher parmi les titres des cartes, utilisez juste les mots-clé que vous avez en tête. Il y a 3 mots-clé que vous ne pouvez pas utiliser directement, parce qu’ils sont réservé par le système de recherche: and
, or
, not
. Si vous voulez quand même les utiliser dans votre recherche, vous pouvez les entourer de guillemets (ie. oranges "and" berries
).
Pour chercher des cartes qui ne correspondent pas au mots-clé, ajoutez le mot-clé not
devant votre recherche (ie. not oranges
). Si vous avez besoin d’exclure les cartes correspondant à une phrase, entourez les mots-clé de guillemets (eg. not "oranges berries"
).
Pour chercher une carte avec une référence spécifique, utilisez #
suivi de la référence (eg. #123
).
Pour chercher une carte qui est dans un groupe, utilisez #
suivi par le nom du groupe. Si le nom du groupe contient des espaces, ignorez-les (ie. pour cherche les cartes dans le groupe “Liste 2”, utilisez #liste2
).
Pour chercher une carte qui a un membre du projet dans au moins un de ses champs, utilisez @
suivi du nom d’utilisateur (eg. @username
). Vous pouvez utilisez @me
pour cherchez vos propres cartes.
@{user name}
et #{List 2}
).
Champs
Vous pouvez chercher des cartes à partir de leurs champs en utilisant l’un des deux syntaxes suivantes: champ=valeur
ou {champ}=valeur
. La première ne peut seulement être utilisée avec des noms de champ sans caractères spéciaux et sans espaces.
Sinon utilisez la dernière (eg. {champ avec espace}=valeur
).
Les opérateurs disponibles sont :
=
: égal à (eg.{Contact} = "john@doe.com"
)!=
: différent de (eg.{Nombre d'heures estimé} != 10
)>
ou>=
: supérieur à et supérieur ou égal à (eg.{Nombre d'heures estimé} > 10
)<
ou<=
: inférieur à et inférieur ou égal à (eg.{Nombre d'heures estimé} <= 10
)~=
: à peu près égal à (pour des valeurs textuelles). (eg.description ~= orange
)
Si le champ est une liste de valeur (comme les champs de type membres), utilisez l’opérateur in
: @username in Assignés
.
Quand on compare des champs, les valeurs peuvent être :
- une valeur vide (qui veut dire que la carte n’a pas de valeur pour ce champ):
empty
(eg. trouver toutes les cartes sans description:description=empty
) - un nombre:
10
ou12.1
ou-3.4
- une chaine de caractères:
mot
ou"plusieurs mots entourés par des guillemets"
yes
ouno
(pour les champs oui/non)- une date: une chaine de caractères entourée de guillemets utilisant le format: YYYY-MM-DD (eg.
"2017-02-05"
). Quelques mots-clé spéciaux peuvent être utilisés en tant que date: today, tomorrow, yesterday. (eg.{due date}<today
) - un membre:
@username
- une référence de carte:
#123
- une référence d’object (voir plus bas)
Vous pouvez aussi utiliser des expressions arithmétiques (ie. 3 + 4
).
Plusieurs champs spéciaux existent :
ref
: référence de carte (eg.ref=123
)title
: titre de carte (eg.title="ma tâche"
)created at
: la date de cration de la carte (eg.{created at}="2017-02-01"
)created by
: l’utilsateur qui a créé la carte (eg.{created by}=@me
)updated at
: date de la dernière mise à jourstate
: l’état de la carte (eg.state=completed
) et quelques aliasstate=todo
: se réferrant àundecided
,accepted
ouwaiting
state=doing
: rse réferrant àin_progress
state=finished
: se réferrant àcompleted
,closed
oudropped
started at
: la dernière date à laquelle la carte est passé dans l’état en cours.finished at
: la dernière date à laquelle la carte est passée dans l’un des états suivants, abandonné, terminé or ferméresolution time
: le temps écoulé entre finished at et started atarchived
: si la carte a été archivé (valeur oui/non:archived=yes
)parent
: id de la carte parent (utilisable dans des requêtes comme{parent} in {champ relation de carte n°1}
ou{parent}=#14
)hlevel
: niveau de hierarchie de la carte dans le projet. Par exemple, pour une sous-carte, cela retournera 2nb children
: nombre de carte enfantsnb comments
: nombre de commentaireslast comment at
: date du dernier commentairemodel
outype
: nom d’un type de carte (eg.model=bug
)workspace
ouproject
: nom d’un workspace (eg.workspace="My Workspace"
)org
ouorganization
: nom d’une organisationteam
: nom de l’équipeform
: nom du formulaire (si la carte a été créée à partir d’un formulaire de projet)form submitted by
: soit{form submitted by}=@username
ou{form submitted by}="email"
si la personne qui soumet le formulaire n’a pas de compte Kantreeshared
: si la carte a un lien public de partage ou non
Vous pouvez utiliser le mot-clé not
devant chacune de ces conditions, pour chercher les cartes qui ne lui correspondent pas (ie. not @me in assignés
).
Combiner des conditions
Vous pouvez utiliser plusieurs conditions dans vos requêtes. Vous n’avez qu’à les mettre les unes à la suite des autres. Toutes les conditions doivent être remplies pour qu’une carte puisse correspondre.
Pour des requêtes plus flexible, vous pouvez combiner des conditions en utilisant les opérateurs logiques :
and
: toutes les conditions doivent être rempliesor
: au moins une des conditions doit être remplie
Si aucun opérateur logique n’est utilisé, and
is used.
Vous pouvez regroupez des conditions entre parenthèses. and
a la priorité sur or
.
Utilisation avancée
Fonctions
Ils existent 2 types de fonctions :
- fonctions qui retournent une valeur (eg.
now()
) - fonctions utilisées comme une condition (eg.
date?("week")
)
Fonctions disponibles :
now()
: retourne l’heure et la date du jourtoday()
: retourne la date du jour sans l’heureperiod(interval)
: retourne un intervale pour faire des opérations sur des dates, par exemplenow() + period("1 week")
. La valeur est suivie par une unité de temps (année, mois, semaine, jour, heure).ago(intervalle)
: retourne la date obtenue si on retranche l’intervalle à la date du jourahead(intervalle)
: retourne la date obtenue si on ajoute l’intervalle à la date du jourweek_start([date])
: retourne la date du premier jour de la semaine qui contient la date en paramètre, si aucun paramètre n’est donné la semaine en cours est utiliséeweek_end([date])
: retourne la date du dernier jour de la semaine qui contient la date en paramètre, si aucun paramètre n’est donné la semaine en cours est utiliséeworkweek_start([date])
: retourne la date du premier jour ouvré de la semaine qui contient la date en paramètre, si aucun paramètre n’est donnée la semaine en cours est utiliséeworkweek_end([date])
: retourne la date du dernier jour ouvré de la semaine qui contient la date en paramètre, si aucun paramètre n’est donnée la semaine en cours est utiliséemonth_start([date])
: retourne la date du premier jour du mois qui contient la date en paramètre, si aucun paramètre n’est donnée le mois en cours est utilisémonth_end([date])
: retourne la date du dernier jour du mois qui contient la date en paramètre, si aucun paramètre n’est donnée le mois en cours est utiliséyear_start([date])
: retourne la date du premier jour de l’année qui contient la date en paramètre, si aucun paramètre n’est donnée l’année en cours est utiliséeyear_end([date])
: retourne la date du dernier jour de l’année qui contient la date en paramètre, si aucun paramètre n’est donnée l’année en cours est utiliséecount_days([start], [stop])
: retourne le nombre de jours dans l’intervalle que represente start et stop. Si aucun paramètre n’est donné, le nombre de jour du mois en cours est retourné.count_working_days([start], [stop])
: retourne le nombre de jours ouvrés dans l’intervalle que represente start et stop. Si aucun paramètre n’est donné, le nombre de jour du mois en cours est retourné.last_moved_in_group_at(group_name, [type_name])
: retourne la date à laquelle la carte a été déplacée pour la dernière fois dans le groupe donnéif(expression, valeur, autreValeur)
: retourne valeur si expression est true et autreValeur si expression est falseas_string(value)
: convertit une valeur en chaine de caractères, par ex as_string({Points})as_date(value)
: convertit une valeur en date, par ex as_date({champ texte})as_number(value)
: convertit une valeur en nombre, par ex as_number({champ texte})size(liste)
: retourne le nombre d’éléments dans une liste, par ex size({assignés})substring(node, start, count)
: renvoie une partie d’une chaine de caractères, par exemplesubstring("hello world", 6, 5) = "world"
concat(value1, value2, ...)
: concatène plusieurs valeurs ensembleround(value, [decimal])
: arrondit un nombre à la décimale choisie (par défaut, renvoie un nombre entier)sum_logs(category_name, field_name, [user], [from_date], [to_date])
: retourne la somme des valeurs des logs ayant le nom et la categorie choisis. Peut être limité à un utilisateur et sur une période donnés. Quand on fait la somme de valeurs de champs de type “Temps”, le résultat sera donné en secondes.count_logs(category_name, [user], [from_date], [to_date])
: retourne le nombre de logs d’une categorie donnée. Peut être limité à un utilisateur et sur une période donnés.card(project_title, card_ref)
: retourne l’id de la carte venant d’un autre projet
Exemple: trouver les cartes qui avaient une échéance il y a 3 jours: {échéance} <= ago("3 days")
Les fonctions conditionnelles disponibles :
full_text_search?(texte)
: vérifie si le titre ou les valeurs des champs de la carte contiennent ce texteis_in_active_group?()
: vérifie si la carte est dans un group qui a des dates de début et de fin et si aujourd’hui est entre ces dates.is_in_group?(nom_groupe, nom_type)
: vérifie si la carte est dans le groupe nom_groupe (nom_type optionnel).was_in_group?(nom_groupe, nom_type)
: verifie si la carte a été dans le groupe nom_groupe (nom_type optionnel).is_in_group_type?(nom_type)
: vérifie si la carte est dans le type de groupe nom_type.date?(date)
: vérifie si au moins un champ de type date de la carte correspond a la date spécifiée entre parenthèse. Exemple de formats valides de date : “05-27-2018” (format MM-JJ-AAAA), “week”, “month”, “year”, “week+1” (pour la semaine prochaine), “week-1” (pour la semaine dernière), “week-2” (pour la semaine avant la dernière)contains_member?(@username)
: vérifie si n’importe quel champ de type membre de la carte contient@username
is_pii?(identifier)
: vérifie si au moins un champ marqué PII a une valeur, et si unidentifier
est fourni (que ce soit un @username ou une chaine de caractère), vérifie si au moins un des champs marqués PII contient identifieris_subscribed?()
: vérifie si vous êtes abonné à une carteparent?(kql_expression)
: vérifie si au moins un parent de la carte correspond à l’expression kql donnéechildren?(kql_expression)
: vérifie si au moins un enfant direct de la carte correspond à l’expression kql donnéedescendants?(kql_expression)
: vérifie si au moins une carte descendant de la carte correspond à l’expression kql donnée (non limité aux sous_cartes)
Références d’object
Les références d’object peuvent être utilisées pour retirer des valeurs d’une carte ou d’un utilisateur. Elles peuvent être utilisées dans des expressions arithmériques ou dans des comparaisons de champs.
Pour obtenir la valeur du champ d’une carte, utilisez la syntaxe suivante : {#ref:champ}
(eg. {#123:Nombre d'heures estimé}
).
Pour obtenir une valeur d’un champ d’utilisateur, utilisez la syntaxe suivante : {@username:champ}
(eg. {@me:email}
).
Les champs suivants sont disponibles pour les utilisateurs : email, username.
Exemples
Trouvez les cartes qui me sont assignées (en utilisant le champ Assignés) :
@me in assignés
Trouvez les cartes qui me sont assignées dans le groupe Backlog :
@me in assignés #backlog
Trouvez toutes les cartes qui arrivent à échéance demain (en utilisant le champ Echéance) :
{échéance}=tomorrow
Trouvez toutes les cartes qui ont le mot “problème” dans leur description (en utilisant le champ Description) :
description ~= problème
Trouvez toutes les cartes qui me sont assignées ou que j’ai créées :
@me in assignés or {created by}=@me
Trouvez toutes les cartes dont l’échéance est dépassée et qui n’ont pas d’assignés :
assignés=empty {échéance}<today
Trouvez toutes les cartes qui sont vieilles de plus de 3 jours et qui n’ont pas de description :
description=empty {created at} > ago("3 days")
Trouvez toutes les cartes qui ont le modèle Bug et qui sont vieilles de plus de 1 semaine :
model=bug {created at} > ago("1 week")