Rapport requête : validation des filtres côté serveur

Par défaut, les filtres d'un rapport requête sont définis uniquement dans le JavaScript du rapport (frappe.query_reports["Nom du rapport"]). Lorsque le rapport s'exécute sans le Desk — via l'API, un rapport préparé ou un envoi automatique de rapport — aucune validation des filtres obligatoires, des options ou des types n'est effectuée.

Cochez la case Valider les filtres (validate_filters, libellé non traduit) sur le document Rapport pour définir les filtres dans la table Filtres et les faire valider par le serveur avant l'exécution du rapport. Le JavaScript du rapport conserve uniquement des comportements comme get_query, fusionnés avec les lignes du serveur par fieldname.

Comportement lorsque la validation est activée

Lorsque Valider les filtres est coché, le serveur, avant d'exécuter le rapport :

• applique les valeurs par défaut des filtres ;
• vérifie que les filtres obligatoires ont une valeur ;
• contrôle les valeurs : options des champs Select, existence et permission de lecture (ou de sélection) des valeurs Link, nombres valides pour Int, Float et Currency, 0 ou 1 pour Check, dates, heures et plages de dates valides ;
• rejette les clés de filtres inconnues (hors lignes de la table et hors clés réservées du framework) ;
• convertit chaque valeur vers le type du champ avant l'exécution.

Sans la case cochée, les filtres ne sont pas validés côté serveur et le serveur exécute le rapport avec les filtres reçus.

Types de filtres disponibles

Avec Valider les filtres, la table Filtres accepte notamment :

• Autocomplétion (Autocomplete) ;
• Liste à sélections multiples (MultiSelectList) : chaque élément est vérifié comme une valeur Link. Le DocType peut être indiqué directement dans Options ou par le fieldname d'un autre filtre de la table, dont la valeur résolue est alors utilisée comme DocType ;
• Plage de dates (DateRange) : la valeur doit être une liste de deux dates valides, la date de début ne devant pas être postérieure à la date de fin.

Règles de configuration des lignes :

• un filtre Lien doit avoir un DocType dans Options ;
• l'option Filtre avec caractère générique est refusé pour les types Liste à sélections multiples et Plage de dates ;
• les types Liste à sélections multiples et Plage de dates ne sont disponibles qu'avec Valider les filtres ;
• les valeurs des filtres Lien dynamique ne sont pas vérifiées contre les enregistrements existants.

Valeurs par défaut

Les valeurs par défaut des filtres suivent les règles des formulaires :

• __user est remplacé par l'utilisateur de la session ;
• « Aujourd'hui » et « Now » sont résolus en date / heure courante du site ;
• les valeurs par défaut enregistrées de l'utilisateur s'appliquent uniquement aux filtres Lien sans valeur par défaut propre, et jamais aux liens vers le DocType User ;
• une valeur par défaut de Liste à sélections multiples ou de Plage de dates est convertie en liste ; une date seule de Plage de dates est étendue en une plage allant de cette date à elle-même.

Validation des valeurs reçues

• une valeur vide (chaîne vide, liste vide ou valeur nulle) est acceptée pour un filtre facultatif, mais un filtre obligatoire sans valeur est rejeté, y compris une Liste à sélections multiples vide ;
• les valeurs non textuelles correspondant à une option d'un champ Select sont acceptées ;
• une valeur Link « fausse » comme 0 est bien vérifiée contre le DocType ;
• les valeurs natives envoyées par l'API (date, datetime, heure) sont acceptées pour les filtres Date, Datetime et Time ;
• les filtres non fournis reçoivent leur valeur par défaut avant la validation.

Où la validation s'applique

• exécution d'un rapport requête, y compris via l'API (frappe.desk.query_report) ;
• ouverture d'un rapport préparé par son nom : les filtres enregistrés sont validés, même lorsqu'ils sont vides ;
• enregistrement d'un Envoi programmé de rapports : les filtres obligatoires du rapport validé sont vérifiés à l'enregistrement ;
• dans le Desk, les filtres des rapports validés sont initialisés avec les valeurs par défaut résolues par le serveur, et les boîtes de dialogue de filtres enregistrés (rapport automatique, graphiques, cartes de nombre) conservent les valeurs effacées des filtres des rapports validés.

Exemple

Le rapport standard Permitted Documents For User (« Documents autorisés par utilisateur ») utilise cette validation : ses filtres user, doctype et show_permissions sont définis dans les lignes du document Rapport, et seul le get_query du filtre doctype reste dans le fichier JavaScript du rapport.