Colonnes Formule, Calculées et Cumulatives à l’aide d’un code

  • Article

Les colonnes Formule, Calculées et Cumulatives sont essentielles, car elles dispensent l’utilisateur de devoir exécuter manuellement des calculs ; l’utilisateur peut ainsi se concentrer sur son travail. Les administrateurs systèmes peuvent définir un champ pour contenir la valeur de la plupart des calculs courants sans avoir à collaborer avec un développeur. Les développeurs peuvent aussi utiliser les fonctionnalités de la plateforme pour effectuer ces calculs plutôt qu’avec du code.

Cet article se concentre sur la façon dont ces colonnes sont définies dans les définitions de colonnes et les API pour interagir avec les colonnes de cumul. Nous ne prenons pas en charge la définition des formules avec du code. Vous devez utiliser Power Apps pour définir les formules pour le type de colonne respectif. Découvrez comment :

Éléments communs et fonctionnalités

Les colonnes Formules, Calculées et Cumulatives partagent certains éléments communs et fonctionnalités, par exemple :

  • Elles sont en lecture seule.
  • Elles ne sont pas spécifiques à l’utilisateur.
    Comme le calcul est effectué avec un compte d’utilisateur système, les valeurs peuvent être basées sur les enregistrements pour lesquels l’utilisateur ne possède pas autrement les privilèges d’affichage, comme les colonnes dont la sécurité est activée au niveau du champ.

Toutes les colonnes qui héritent de AttributeMetadata ont une propriété SourceType pouvant contenir les valeurs affichées dans le tableau suivant.

active Description
Null Type de colonne non valide pour être une colonne de formule, calculée ou cumulative.
0 Une seule colonne. La colonne n’est pas définie comme colonne de formule, calculée ou colonne cumulative.
1 Colonne calculée
2 Colonne cumulative
3 Colonne Formule

Les colonnes Formule, Calculées et Cumulatives sont basées sur des types de colonnes existantes qui héritent de AttributeMetadata. Les tableaux suivants présentent les types de colonnes disponibles et les types de sources pris en charge :

Type Types de sources pris en charge
BooleanAttributeMetadata Formule, calculé et cumul
DateTimeAttributeMetadata Formule, calculé et cumul
DecimalAttributeMetadata Formule, calculé et cumul
StringAttributeMetadata Formule, calculé et cumul
IntegerAttributeMetadata Calculés et cumulatifs uniquement
MoneyAttributeMetadata Calculés et cumulatifs uniquement
PicklistAttributeMetadata Calculés et cumulatifs uniquement

Chacun de ces types de colonne a les propriétés suivantes pour prendre en charge les formules, calculs et les reports.

Property Définition
FormulaDefinition Contient la définition de la formule utilisée pour effectuer le calcul ou le report. Les colonnes de formules sont définies à l’aide de YAML. Les colonnes calculées et cumulatives sont définies à l’aide de XAML. La seule façon prise en charge de modifier cette valeur consiste à utiliser l’éditeur Power Apps.
SourceTypeMask La valeur de masque de bits de cette propriété en lecture seule décrit les types sources utilisés dans la formule de la colonne ou si la formule de la colonne n’est pas valide.

- 0 : Undefined. Valeur par défaut des colonnes simples et cumulatives.
- 1 : Simple. La colonne de formule ou calculée fait référence à une colonne dans le même enregistrement.
- 2 : Related. La colonne de formule ou calculée fait référence à une colonne dans un enregistrement associé.
- 4 : Logical. La colonne de formule ou calculée fait référence à une colonne du même enregistrement stocké dans une autre table de base de données. Pour plus d’informations, consultez Colonnes logiques
- 8 : Calculated. La colonne de formule ou calculée fait référence à une autre formule ou colonne calculée.
- 16 : Rollup. La colonne de formule ou calculée fait référence à une colonne cumulative.
- 32 : Invalid. La colonne de formule ou calculée ou cumulative n’est pas valide.
Généralement, il s’agit d’une colonne non valide qui fait référence à une colonne qui n’existe plus.

Remarque : une ou plusieurs de ces conditions peuvent être vraies pour n’importe quelle colonne calculée ou cumulative. Comme il s’agit d’une valeur de masque de bits, vous pouvez trouver utile d’utiliser l’Énumération SourceTypeMasks lors de l’exécution d’opérations au niveau du bit.

Colonnes de formule ou calculée

Les colonnes de formule ou calculée en temps réel quand elles sont récupérées. Les colonnes de formule ou calculée peuvent être composées en utilisant différents types de données. Par exemple, une colonne calculée Integer peut référencer les valeurs des colonnes Decimal ou Currency.

Les valeurs de colonnes de formule ou calculée sont disponibles dans le pipeline du plug-in de récupération. La post-image de la mise à jour ou de la création d’un enregistrement de table contient la valeur de colonne calculée de l’étape 40. Pour plus d’informations : Pipeline d’exécution des événements et Images d’entité

Limitations

Les colonnes de formules et de calculs présentent les limitations suivantes :

Colonnes de formule

  • Les colonnes de formule ne disposent pas de valeurs lorsqu’un utilisateur avec un client mobile est en mode hors connexion.
  • Les propriétés de définitions de colonne MaxValue et MinValue ne peuvent pas être définies sur les colonnes de formule. Plus d’informations : Directives et limitations

Colonnes calculées

Vous ne pouvez pas utiliser de valeurs dans les colonnes calculées sur une valeur logique dans la même table pour trier les données renvoyées par une requête. Bien que votre requête puisse spécifier que les résultats doivent être classés à l’aide d’une colonne calculée, le sens du tri est ignoré et ne lève aucune erreur. Si la colonne calculée ne fait référence qu’à des valeurs simples dans le même enregistrement, le tri fonctionne normalement. Vous pouvez déterminer les sources utilisées dans une colonne calculée à l’aide de la propriété SourceTypeMask sur les définitions de colonne.

  • Seules les colonnes d’une table parent immédiate peuvent être utilisés dans une colonne calculée.
  • Les requêtes enregistrées, les graphiques et les visualisations peuvent comporter un maximum de 50 colonnes calculées uniques.
  • Les colonnes calculées peuvent faire référence à d’autres colonnes calculées dans leur formule, mais elles ne peuvent pas faire référence à elles-mêmes.
  • Les colonnes calculées ne disposent pas de valeurs lorsqu’un utilisateur avec un client mobile est en mode hors connexion.
  • Les propriétés de définitions de colonne MaxValue et MinValue ne peuvent pas être définies sur les colonnes calculées

Colonnes cumulatives

Étant donné que les colonnes cumulatives persistent dans la base de données, elles peuvent être utilisées pour filtrer ou trier, tout comme les colonnes normales. Tout type de processus ou de plug-in utilise la valeur calculée de la colonne la plus récente. Les tâches système calculent les valeurs de colonne Cumulatives de façon asynchrone. Les administrateurs définissent à quel moment une tâche est exécuté ou suspendue. Par défaut, chaque colonne est mise à jour toutes les heures.

Lorsqu’une colonne cumulative est créée ou mise à jour, une tâche Champs cumulatifs calculés en masse est planifiée pour s’exécuter en 12 heures. Le délai de 12 heures est conçu pour exécuter cette opération sollicitant de nombreuses ressources pendant une période qui affecte le moins les utilisateurs. Une fois la tâche terminée, sa prochaine exécution est planifiée 10 années plus tard. Si un problème survient lors du calcul, il sera déclaré avec la tâche système. Localisez la tâche système pour trouver les erreurs avec les champs cumulatifs. Pour trouver la tâche système, voir Afficher les tâches de cumul.

Conseil

Comme développeur testant une solution dans un environnement de développement, vous ne pouvez peut-être pas attendre 12 heures. Vous pouvez faire en sorte que cela se déroule plus rapidement. Dans la liste Tâches système, utilisez la vue Tâches système récurrentes pour filtrer la liste et rechercher la tâche Calculer en masse les champs cumulatifs. La tâche étant sélectionnée, utilisez Autres actions > Reporter, puis définissez la date avec une valeur plus proche.

Si vous souhaitez déclencher la création d’une tâche Calculer en masse les champs cumulatifs par programmation, extrayez AttributeMetadata pour la colonne cumulative à l’aide de RetrieveAttributeRequest et UpdateAttributeRequest pour mettre à jour la colonne sans apporter de réelle modification.

La tâche Calculer en masse les champs cumulatifs se produit immédiatement quand une solution contenant une colonne cumulative est importée. Cela suppose que vous installiez des solutions pendant une période qui n’impactera pas défavorablement les utilisateurs.

Chaque colonne cumulative pour une table comprendra également deux colonnes de support pour la colonne cumulative :

  • <attribute SchemaName>_Date : DateTime – Date du dernier calcul du cumul.
  • <attribute SchemaName> _State : Integer – État du calcul du report. Pour plus d’informations : Valeurs d’état du report

Valeurs de l’état du report

L’état d’un calcul de colonne cumulative est disponible dans la colonne <attribute SchemaName>_State correspondante et dans la propriété CalculateRollupFieldResponse.FieldState . Les valeurs qui indiquent l’état sont répertoriées dans le tableau suivant.

Valeur de l’état Description
0 NotCalculated : la valeur de la colonne reste à calculer.
1 Calculated : La valeur de la colonne a été calculée en fonction de l’heure de la dernière mise à jour dans la colonne <attribute SchemaName>_Date.
2 OverflowError : le calcul de la valeur de colonne a conduit à une erreur de dépassement de la capacité.
3 OtherError : le calcul de la valeur de colonne a échoué en raison d’une erreur interne ; la prochaine série de calculs la résoudra probablement.
4 RetryLimitExceeded : le calcul de la valeur de colonne a échoué, car le nombre maximal de nouvelles tentatives pour calculer la valeur a été dépassé en raison du nombre élevé de conflits de simultanéité et de verrouillage.
5 HierarchicalRecursionLimitReached : le calcul de la valeur de colonne a échoué, car la limite maximale de détail de la hiérarchie du calcul a été atteinte.
6 LoopDetected : le calcul de la valeur de colonne a échoué, car une boucle récursive a été détectée dans la hiérarchie de l’enregistrement.

Extraire immédiatement une valeur calculée de colonne cumulative

Les colonnes cumulatives prennent en charge un message CalculateRollupField que les développeurs peuvent utiliser pour calculer une valeur de colonne cumulative à la demande. Pour le kit de développement logiciel (SDK), utilisez la classe CalculateRollupFieldRequest et pour l’API Web, utilisez la fonction CalculateRollupField

Ce message est une opération synchrone uniquement pour la colonne identifiée dans la requête. Si la valeur de cet enregistrement est incluse comme composante d’autres colonnes cumulatives, les valeurs de ces colonnes ne prendront pas en compte l’éventuelle modification de valeur provoquée par cette méthode avant que ne se produisent les travaux asynchrones régulièrement planifiés exécutant ces calculs.

Limitations

  • Les colonnes cumulatives ne peuvent pas être utilisées comme événement de workflow ou condition d’attente. Ces colonnes ne déclenchent pas l’événement pour déclencher des workflows.
  • Les colonnes ModifiedBy et ModifiedOn de la table ne sont pas mises à jour quand la colonne cumulative est mise à jour.
  • Un maximum de 100 colonnes cumulatives peuvent être définies dans une organisation. Chaque table ne peut pas avoir plus de 10 colonnes cumulatives.
  • Une formule de colonne cumulative ne peut pas faire référence à une autre colonne cumulative.
  • Une formule de colonne cumulative ne peut pas faire référence à une colonne de formule ou calculée complexe. Seule la colonne de formule ou calculée qui référence des colonnes simples du même enregistrement peut être utilisée avec les reports.
  • Une formule de colonne cumulative ne peut pas contenir des enregistrements de relations plusieurs-à-plusieurs (N:N). Elle peut uniquement contenir des enregistrements de relations un-à-plusieurs (1:N).
  • Les formules de colonne cumulative ne peuvent pas utiliser les relations un-à-plusieurs (1:N) avec la table ActivityPointer ou ActivityParty.

Énumération SourceTypeMasks

La propriété SourceTypeMask des colonnes qui prennent en charge les colonnes calculées et cumulatives contient une valeur de masque de bits. Pour extraire les informations pertinentes de la valeur, il est utile d’avoir une énumération lors de l’exécution d’opérations au niveau du bit. Utilisez l’énumération SourceTypeMasks suivante lors de la comparaison de la valeur de propriété SourceTypeMask.

 public enum SourceTypeMasks  
{  
    /// <summary>  
    /// Undefined: 0 - The default value for simple and rollup columns.  
    /// </summary>  
    Undefined = 0,  
    /// <summary>  
    /// Simple: 1 - The calculated or formula column refers to a column in the same record.  
    /// </summary>  
    Simple = 1,  
    /// <summary>  
    /// Related: 2 - The calculated or formula column refers to a column in a related record.  
    /// </summary>  
    Related = 2,  
    /// <summary>  
    /// Logical: 4 - The calculated or formula column refers to a logical column.  
    /// </summary>  
    Logical = 4,  
    /// <summary>  
    /// Calculated: 8 - The calculated or formula column refers to another calculated column.  
    /// </summary>  
    Calculated = 8,  
    /// <summary>  
    /// Rollup: 16 - The calculated or formula column refers a rollup column.   
    /// </summary>  
    Rollup = 16,  
    /// <summary>  
    /// Invalid: 32 - The calculated,formula, or rollup column is invalid.  
    /// Typically this would be where a field refers to a column that no longer exists.   
    /// </summary>  
    Invalid = 32  
}

Voir aussi

Définitions de colonne
Utiliser des colonnes de formule (version préliminaire)
Définir des colonnes calculées
Définir des colonnes cumulatives
Exemple : Cumuler les enregistrements relatifs à un enregistrement spécifique

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).