Filtres

Le filtrage permet de restreindre les entités listées dans les opérations de découverte ou de listage, telles que la recherche, les vues en liste ou les éléments du tableau de bord.

Cette fonction utilise des règles exprimées selon une syntaxe particulière, qui prend la forme d'un arbre logique constitué d'assertions. Elle permet de définir des filtres complexes correspondant par exemple à des règles métier du type "factures impayées de plus de 3 mois" ou "dossiers de demande de crédit complets à traiter par mon service".

Les éléments de cet arbre sont de deux types :

• des comparaisons entre les valeurs, avec des opérateurs comme égal à, supérieur à, contient.
• des fonctions logiques permettant de conditionner plusieurs autres éléments, avec des opérateurs comme et, ou.

Principes de base

Les règles de filtrages possèdent une propriété de base filter qui comporte au moins un élément. Les éléments sont des objets comportant

• une propriété $func qui contient le nom de la fonction utilisée
• une propriété $vars qui contient les arguments passés à la fonction.

filter:
    $func: {{nom de la fonction}}
    $vars:
        var1: {{expression de l'argument 1}}
        var2: {{expression de l'argument 2}}
        ...

L'élément racine peut être une fonction de comparaison simple ou bien une fonction de logique booléenne qui associe deux autres éléments.

Les valeurs peuvent être

• des propriétés des entités
• des valeurs constantes
• des fonctions ou mot-clés retournant une valeur ou un indicateur booléen

Fonctions de comparaison

Une fonction de comparaison est constituée de

• un opérateur de comparaison
• deux expressions de valeur à comparer (droite et gauche)

$func: {{fonction de comparaison}}
$vars: 
    field: {{expression de la valeur à comparer}}
    value: {{expression de la valeur de comparaison}}

Les fonctions de comparaison sont les suivantes :

• equals retourne vrai si les deux arguments sont strictement identiques et de même type
• different retourne vrai si les deux arguments sont différents
• lesser retourne vrai si l'argument de gauche est strictement inférieur à l'argument de droite
• lesserOrEqual retourne vrai si l'argument de gauche est inférieur ou égal à l'argument de droite
• greater retourne vrai si la valeur de gauche est strictement supérieur à la valeur de droite
• greaterOrEqual retourne vrai si l'argument de gauche est supérieur ou égal à l'argument de droite

"filter": {
    "$func": "equals",
    "$vars": { 
        "field": "lifecycle.currentStatus",
        "value": "workingCopy_draft"
    }
}

La fonction like retourne vrai si l'argument de gauche correspond au masque fournit dans l'argument de droite. Le caractère % est un caractère joker qui remplace un ou plusieurs autres caractères. Le caractère _ est un caractère joker qui remplace un seul caractère.

"filter": {
    "$func": "like",
    "$vars": { 
        "field": "entryType.identifier",
        "value": "%facture%"
    }
}

La fonction ilike est similaire à like mais ne tient pas compte de la casse.

Fonctions booléennes

Une fonction booléenne est constituée de

• un opérateur logique
• un ou deux éléments logiques

$func: {{fonction booléenne}}
$vars: 
    left: {{expression logique de gauche}}
    right: {{expression logique de droite}}

Les fonctions logiques sont les suivantes :

• and retourne vrai si les deux éléments droite et gauche sont vrais
• or retourne vrai si l'un des deux éléments est vrai

"filter": {
    "$func": "and",
    "$vars": {
        "left": {
            "$func": "equals",
            "$vars": {
                "field": "lifecycle.status",
                "value": "workingCopy"
            }
        },
        "right": {
            "$func": "equals",
            "$vars": {
                "field": "lifecycle.status",
                "value": "current"
            }
        }
    }
}

Expression de valeurs constantes

Les valeurs constantes sont exprimées directement dans l'argument souhaité, par exemple l'argument value d'une comparaison, sous la forme une chaîne de caractères, d'un nombre, d'un booléen ou toute autre valeur d'un type accepté en tant qu'argument de la fonction.

Exemple avec une chaîne de caractères :

"filter": {
    "$func": "equals",
    "$vars": { 
        "field": "entryType.identifier",
        "value": "valeur chaîne de caractères"
    }
}

Exemple avec un nombre :

"filter": {
    "$func": "lesser",
    "$vars": { 
        "field": "size",
        "value": 1234
    }
}

Exemple avec un booléen :

"filter": {
    "$func": "equals",
    "$vars": { 
        "field": "completeness:complete",
        "value": true
    }
}

Propriété des entités

Les propriétés des entités sont accessibles en indiquant leur localisation dans l'argument field.

field: {{propriété}}

La localisation peut être préfixée du type de l'entité suivi du nom de la propriété, séparés par un point, à la manière des noms de table et de schéma dans le langage SQL.

field: {{type}}.{{propriété}}
field: entry.createdAt
field: user.identifier

La liste des propriétés dépend du type de l'objet, mais il existe un certain nombre de propriétés communes ou courantes listées ci-après :

• createdAt : Date et heure de création de l'entité dans le système
• createdBy : identifiant unique de l'utilisateur qui a créé l'entité
• identifier : identifiant métier de l'entité
• owner : identifiant unique de l'utilisateur propriétaire de l'entité
• displayName : nom affiché, intitulé ou libellé de l'entité
• description : description de l'entité

Exemple avec le nom affiché :

"filter": {
    "$func": "ilike",
    "$vars": { 
        "field": "displayName",
        "value": "%validé"
    }
}

Certaines propriétés sont des groupes qui comportent plusieurs propriétés, accessibles en précisant leur chemin.

C'est le cas du sous-type de l'entité, dont le nom dépend du type : entryType pour les dossiers, binaryContentType pour les documents numériques, userType pour les utilisateurs, etc. Les propriétés accessibles pour le sous-types sont les suivantes :

• identifier : identifiant métier du type
• displayName : nom affiché, intitulé ou libellé du type
• description : description du type

Exemple avec l'identifiant du type de document numérique :

"filter": {
    "$func": "equals",
    "$vars": { 
        "field": "binaryContentType.identifier",
        "value": "facture"
    }
}

Le groupe lifecycle cntient l'information sur le cycle de vie de l'entité :

• status : statut dans le cycle de vie système, soit workingCopy, current, preserved ou residual
• subStatus : sous-statut personnalisé, dépendant d'une politique de cycle de vie définie par l'administrateur

Exemple avec le sous-statut indiquant un document à valider :

"filter": {
    "$func": "equals",
    "$vars": { 
        "field": "lifecycle.subStatus",
        "value": "a_valider"
    }
}

Le groupe attributes nécessite d'ajouter deux points avant le chemin dans le schéma de données personnalisé:

"field" : "attributes:{{nom du schéma}}.{{chemin de la propriété}}"

Par exemple, dans un schéma "Contrat", on souhaite indiquer la propriété "Numéro" :

"filter": {
    "$func": "equals",
    "$vars": { 
        "field": "attributes:Contrat.numero",
        "value": "1234567890"
    }
}